Monday, September 11, 2006

Intention Revealing Interfaces, Bad Naming and Maintenance

As an architect I am trying to guide the other programmers on my current project that the design of our components is very important for the reusability of our solution. There are some bad naming of methods and properties that makes me think of the famous "How to write unmaintainable code" article, and to make things worse, this especially applies to some core common objects (which are of course reused from another project group :).

The naming focus is on intention revealing interfaces, but still new methods/properties/class members with creative misspelling, abstract names such as PerformDataFunction, abbreviations such as IntAccount (integer, internal, international ?) , pops up in the design now and then.

What triggered me to write this post is misleading name reuse. One of the domain objects is the AccountNumber and the account number does either belong to the bank or it does not. In addition, an account belong to the bank can be an internal account for e.g. book-keeping, currency exchange, etc. Looking through the .IsXxx properties of the object I found .IsInternal, but no property to tell me if the account belongs to the bank or not. As the object did not reveal its intention to me, I had to find and ask the developer. And surprise, surprise; the domain term 'is internal' had been used as the 'own bank' indicator as it "seemed natural at the time".

"So why did you not change it when you discovered the misleading term?" I asked, knowing the answer: "I am afraid that it will break the other project. Also, it might be a lot of work to make it build after the refactoring". I know that the "other project" has low unit tests coverage and a complicated build configuration, but none of the solutions using the common component is in production yet.

This leads me to the difference between public and published, i.e. it is the published parts of your object model/API you cannot change (it is the contract of your service). The public parts is subject to change without notice. As none of the components are published yet, we decided to refactor the design of the object model to comply with best practices, now rather than later.

The main goal of the refactoring of our components is to comply with some of the central design goals of our components: "power of sameness" and "tools for communication (revealing intention)". As it is now, coding against the common core components is like being an archeologist; piecing together fragments left behind by long gone developers.

Being complex is easy, being simple is hard - Brad Abrams

No comments: