[TUHS] daemons are not to be exorcised

[Dan Cross]

On Wed, Mar 21, 2018 at 1:28 PM, Paul Winalski <paul.winalski at gmail.com>
wrote:

> On 3/21/18, Arthur Krewat <krewat at 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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20180321/29852f97/attachment.html>