Collective Wisdom from the Experts 125
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. If you need to explain a change, do so in the version control system
check-in message and not in the code.
What can you do to actually make your code tell the truth as clearly as pos-
sible? Strive for good names. Structure your code with respect to cohesive
functionality, which also eases naming. Decouple your code to achieve
orthogonality. Write automated tests explaining the intended behavior 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 any other composition, such as a poem, an essay, a pub-
lic blog, or an important email. Craft what you express carefully, so that it
does what it should and communicates as directly as possible what it is doing;
so that it still communicates your intention when you are no longer around.
Remember that useful code is used much longer than ever intended. Mainte-
nance programmers will thank you. And, if you are a maintenance program-
mer and the code you are working on does not tell the truth easily, apply the
aforementioned guidelines in a proactive manner. Establish some sanity in the
code, and keep your own sanity.