Collective Wisdom from the Experts 33
Comments are not evil. They are as necessary to programming as basic branch-
ing or looping constructs. Most modern languages have a tool akin to javadoc
that will parse properly formatted comments to automatically build an API
document. This is a very good start, but not nearly enough. Inside your code
should be explanations about what the code is supposed to be doing. Coding
by the old adage, “If it was hard to write, it should be hard to read,” does a
disservice to your client, your employer, your colleagues, and your future self.
On the other hand, you can go too far in your commenting. Make sure that
your comments clarify your code but do not obscure it. Sprinkle your code
with relevant comments explaining what the code is supposed to accomplish.
Your header comments should give any programmer enough information to
use your code without having to read it, while your inline comments should
assist the next developer in fixing or extending it.
At one job, I disagreed with a design decision made by those above me. Feel-
ing rather snarky, as young programmers often do, I pasted the text of the email
instructing me to use their design into the header comment block of the file. It
turned out that managers at this particular shop actually reviewed the code when
it was committed. It was my first introduction to the term career-limiting move.