Only the Code Tells the Truth
The ultimate meaning of a program is given by the running code. If this is in binary form, it might not be easily read. However, the source code should be available if it is your program. Looking at the source code the meaning of the program is told, since this is the only relevant thing to look at. The nicest requirements document is always lying, since it does not contain the true story of what the program is actually doing, only the intentions of the requirements analyst. A design document can capture the planned design, but might have lost its link with the current implementation. All these documents might never have been written, or are lost when your code needs to be changed in the future. The only thing left actually might be only the code.
Ask yourself, is your code telling you or any other programmer what it is doing?
You might say, "Oh my comments will tell". Please consider, comments are not running code. They can be as wrong as the other documents. There has been a tradition saying comments are good, so some naive programmers started to write more and more comments, even explaining trivia that is said by the code to a professional programmer. That is wrong. If your code needs comments, consider refactoring it so it doesn't. Lengthy comments can clutter screen space and might even be hidden automatically by your IDE.
What can you do to actually make your code tell the truth? Strive for good naming of program elements! Structure your code with respect to cohesive functionality, which also eases naming! De-couple your code to achieve orthogonality! Write automated tests explaining the intended behaviour and check the interfaces! Refactor mercilessly when you learn how to code a simpler, better solution! Make your code as simple as possible to read and understand!
Treat your code like a poem or an essay. Carefully craft your expression, so that it does what it should and actually tells a professional developer like you what it is doing, even when you are not or no longer around. Remember, useful code is used much longer than ever intended. Your maintenance programmers will thank you. Don't forget, if you are the maintenance programmer and the code you've got is not easily telling the truth, apply the guidelines above in a pro-active manner, to establish sanity of the code and keep your own sanity.
This work is licensed under a Creative Commons Attribution 3
Back to 97 Things Every Programmer Should Know home page