On Wed, Mar 21, 2018 at 1:28 PM, Paul Winalski <paul.winalski(a)gmail.com>
wrote:
On 3/21/18, Arthur Krewat <krewat(a)kilonet.net>
wrote:
[...]
I call bullshit on that. Not commenting is lazy. There's no reason NOT
to comment.
Amen to that! Good comments are one of the things that distinguishes
Software Engineering from mere programming.
Critical to that, however, is the adjective "good", as in "good
comments."
Writing comments can be incredibly useful, but writing *good* comments is a
learned skill that requires judgement and taste.
Much ado is made nowadays about the "craft" of programming. I dislike this
analogy for a number of reasons, but there's no denying that good
programming has a craft element to it, and I claim that good commenting is
one of the harder of the craft skills to master. In particular, there *are*
good reasons NOT to comment something: the code is so obvious the comment
would just be a restatement of the manifestly evident, but with the added
visual clutter and cognitive load imposed by simply existing and the added
maintenance burden of being kept in sync. When I see a comment, I often
take it as an indication that something notable is happening: if the
comment is superfluous then I'm left wondering WHY it's there and what
about the code I'm missing. Similarly, comments must be maintained: my
experience is that out-of-date comments that have fallen out of sync with
the code are strictly a liability. Finding balance between the costs of
commenting and the positive benefits of comments takes time to develop.
When I was younger, I dressed somewhat better than I do now and when I was
in the Marines I once found myself in a social situation where it made
sense to wear a tweed jacket. Another Marine introduced me to the concept
of, "always, sometimes, never" vis which of the three buttons on the front
of my jacket to button: top button always, middle button sometimes, bottom
button never (whether this is good fashion advice or not is another
matter). I think that something analogous is true of writing good comments:
1. A comment should never simply parrot the code: i++; // Increment i.
2. A comment should sometimes explain *what* the code is doing.
3. A comment should always explain *why* the code is doing what it's doing.
Note that these are specific to comments, not to code: it does not follow,
for example, that a line or stanza of code should always be adorned with a
comment explaining why it exists: (think, `i++; // Increment the array
index for the next iteration of the loop.` Ugh).
Btw, this is something I think that Unix did very well.
- Dan C.