When code goes bad: What to watch for
Emergent Design: Pathologies uncovered
Book extract, part five Scott Bain’s book, Emergent Design: The Evolutionary Nature of Professional Software Development by Addison Wesley, looks at the principles involved in building and maintaining robust, reliable, and cost-effective code. In this, our concluding extract, Scott identifies the pathologies in code when coupling, cohesion, and redundancy have not been adhered to.
It is important to know the qualities you want your code to have, but it is also important to empower yourself with a set of indicators that tell you that you are heading in the wrong direction. Ideally, I would like to know I am doing something I should not do before I have done very much of it. Also, we often are called upon to evaluate other people's code, or to revisit our own code from the recent or distant past.
Pathologies help us here. In truth, code, design, and system pathologies could be the subject of an entire book, but there are a few really high-leverage indicators that we can use as a basic set. Not surprisingly, they tie into the qualities that I listed earlier: coupling, cohesion, and eliminating redundancy.
Indicators of weak cohesion
Here are some indicators of weak cohesion:
- Difficulty naming. I would like the names of classes, methods, and other entities (delegates, packages, and so on) to reveal their intentions in their names. I would also like my names to be relatively brief, and yet still tell the whole story.
- When a class or method has a long name, or a vague name, the reason often is that a really informative name is very difficult to create, due to the fact that the class or method does a number of different things. This, of course, is weak cohesion, and causes lots of other problems anyway. When I cannot name things the way I want to, I suspect that my entities do too much.
- Large tests. When a class has multiple responsibilities, it can create large tests, because the test must cover all the possible combinations of these responsibilities.
- Large classes and methods. When a class or a method gets big and requires lots of scrolling in your integrated development environment, or when it is hard to see well, I usually suspect weak cohesion. This is not an absolute; algorithms themselves can get large and yet still be about one responsibility, but it is, at least, something to investigate when I see it.
A student once told me a story that is pretty illustrative and also kind of funny. He was given a class to refactor. Someone had written the class in C#, but clearly did not know much about object orientation. The class worked fine (the author had been, obviously, a skilled programmer), but nobody could or would touch it. It was, essentially, one huge method.
He started by doing what I would probably do; he just scanned through the code without really reading it thoroughly, just to determine how tough this job was going to be. He was, of course, being asked how long this was going to take.
As he scanned along, hitting Page Down over and over, suddenly all the code disappeared from the screen. A few more page downs revealed blank screen after blank screen, and then suddenly the code was back again.
Designs don't emerge! Speak english, please.
Design is a priori, emergence is post facto.
Evolution doesn't "design" (unless you are a loony), emergence is an evolutionary behaviour.
Bah! Humbug! So, are you a loony?
Perhaps you are trying to avoid the "architecture" word?
I think we all need to take one thing into consideration, and remember the fact that many of the developers we are speaking of do not have English as their first language.
We also need to remember the fact that everyone has their own unique style of coding and depending on the reason for writing the code, will determine how they anotate that. For example, if someone is simply writing code for a private project which will then be sent to the customer, then we should not assume that they will include comments, or at least comments that we expect to match exactly what we are looking for. Further to that, I don't think that it's really a right to be able to complain about something that was given to you for free in the first place. I know some people will be thinking, don't release something if it isn't complete, seriously though don't use it or read it, if you don't agree with it!
Manners, more than anything.
Comments don't execute
I believe that comments should be kept to a minimum. I will also agree with the 'why' and not the 'what'. If you want to know what a piece of code does, reading the comments won't help. In fact, it will probably cause you to make wrong assumptions. Remember, the comments don't execute, the code does.