(^124) 97 Things Every Programmer Should Know
Only the Code Tells the Truth .......................
Peter Sommerlad
THE ULTiMATE SEMANTiCS OF A PROGRAM is given by the running code. If
this is in binary form only, it will be a difficult read! The source code should,
however, be available if it is your program, any typical commercial software
development, an open source project, or code in a dynamically interpreted
language. When you look at the source code, the meaning of the program
should be apparent. To know what a program does, the source is ultimately all
you can be sure of looking at. Even the most accurate requirements document
does not tell the whole truth: it does not contain the detailed story of what the
program is actually doing, only the high-level intentions of the requirements
analyst. A design document may capture a planned design, but it will lack the
necessary detail of the implementation. These documents may have lost sync
with the current implementation...or may simply have been lost. Or never
written in the first place. The source code may be the only thing left.
With this in mind, ask yourself how clearly your code is telling you or any
other programmer what it is doing.
You might say, “Oh, my comments will tell you everything you need to know.”
But keep in mind that comments are not running code. They can be just as
wrong as other forms of documentation. There has been a tradition of say-
ing that comments are unconditionally a good thing, so some programmers
unquestioningly write more and more comments, even restating and explaining
trivia already obvious in the code. This is the wrong way to clarify your code.