So I have become a superhero – I am fighting evil in code comments. For those of you that know me, I always talk about myself as a power electronics hardware and control person. And since about 1997 I have designed control systems that for the most part have been implemented in code of some kind. If you had told me back in 1991 when I finished my Masters that I’d end up being a software person I’d have told you that this was so unlikely that I could not see it happening. And now I spend the balance of my time looking at code. Typically it is VHDL code, Verilog Code, C code or Python code and sometimes I look at C++ code. When I look at this code I am trying to work out what the code does, usually because the code is not doing what it is meant to. Whether it is the pulse or PWM generator code for a DC to DC converter or the repetitive filter necessary to minimise the harmonic content in a UPS voltage waveform it always comes down to looking at the code. So how do you know if the comments are evil? How do you go about fighting evil in your code. Some comments on comments.
The use of requirements, design records, interface specifications, verification test plans, code testing tools, unit testing, version control, automated documentation extraction like doxygen, and code reviews does not ever seem to ever be enough to get the code to do what it needs to.
And then there are the comments that I see in the code. This is the most amazingly varied and strange part of the code review experience. There seems to be no agreement on
- Why comments are in the code?
- What goes in a comment?
- Who the comment is for?
- Why the comment did not get maintained when the code was changed?
The answer to the last question is the reason that 15% (from ELMG Digital Power Polls) of everyone who codes insists that they will not ever use comments. (This is my present opinion and most frequent practice for VHDL and Verilog)
The answer to the other three questions causes discussions of a vehemence that only software people can bring to an argument.
I have a collection of articles and opinions that are from some of the best in the embedded software development space. And I have a collection of articles and opinions that are from some of the best in the software space.
The article that this post is named for is from Michael Sorens. He is worth reading for all good advice about things software development.
This is the article – it is a long read and is quite confronting to software people.
Here are a few excerpts.
What’s Wrong with Comments
The problems with comments are many and varied:
- Over time, and not intentionally, comments can lie, so can lead to misinterpreting the code if you happen to believe the comment.
- Writing comments takes time, more so if you choose a commenting style that requires a lot of time to look pretty, so strive for simplicity.
- Comments make a file longer and can often introduce unnecessary clutter, thus requiring more time to read. Steve Smith, in When to Comment Your Code, reminded me of a very relevant quote from that classic tome on writing, The Elements of Style, and it applies just as validly to code: “Omit needless words. Vigorous writing is concise. A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts.”
- Comments often attempt to explain what or how, which tends to merely repeat the code; comments should always address the why.
- In maintaining code you also have to maintain any associated comments too, thus requiring more effort.
- Writing comments that are clear rather than cryptic is hard. I recent comment (pun intended) I read on this was enlightening: if the code was written in a confusing manner why would you expect the code author to suddenly be able to write comments about it clearly?
As I have said here, and you may have seen elsewhere, comments frequently lie. What does that really mean? Here’s an example from Dietrich’s article along with his commentary:
// Returns x + y or, if x or y is less than zero, throws an exception
public int Add(int x, int y)
{
return x + y;
}
What happened here? When you put on your code archaeology hat, you’ll probably conclude that a guard condition once existed. Someone deleted that guard condition but didn’t think to update the now-nonsensical comment. Oops.
Oops, indeed! Comments, unlike code, are not checked at edit time (unless you’re writing doc-comments, discussed later) or at compile-time or at runtime. You cannot lint your comments. You cannot unit test your comments. In other words, there are no safeguards. Thus, whether you are dealing with good comments or evil comments, you should strive to minimize them so they do not become stale or downright misleading, as in the above example.
Many developers do not like to write documentation of any sort, and that includes comments. (For a good list of excuses reasons, see Why programmers don’t comment their code. But commenting too little (or not at all) is just as bad as commenting too much. As I and many others have stated, comments are often necessary but try to keep them to a minimum.
How Evil is your comment? Fighting evil in code comments.
In ELMG Digital Power Polls most people answer that most of their comments are a description of what or how the code does or works (56%) and repeating the code (75%) and no one (0%) respond that their comments are why the code is the way it is. And this is pretty much exactly the opposite of good or best practice using the “evil scale” in the diagram below.
Check out the article. It is worth a look to make comments more mindful and less evil.