97 Things Every Programmer Should Know

Chapter 62. 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 saying that comments are unconditionally ...