21 Mar
2018
21 Mar
'18
11:33 p.m.
I think there's a middle ground. saying "this is a loop" is not
informative. saying "I did this as a loop because..." can be very
informative.
I think with short circuit evaluation and side-effects in C, this kind
of code is especially worth commenting: people need to remember the
right hand side of a complex set of expressions might actually not
have done anything.
Here at IETF a really cute corner-case of optimization-for-bug came
up. Somebody who thought they had worked out a given packet in UDP dns
messages always had a pair of specific chars 0x0c and 0xc0 in sequence
(or something) and coded for it, not realizing they were coding below
the outcome of a DNS label compression pattern which didn't always
hold. Sometimes, people code from faulty or incomplete information. So
this one, (for instance) would have been much better commented than
not.
It would have let the following people hit the coder with a thin whippy stick.
On Wed, Mar 21, 2018 at 5:28 PM, Paul Winalski <paul.winalski(a)gmail.com> wrote:
On 3/21/18, Arthur Krewat <krewat(a)kilonet.net>
wrote:
It was instilled in me early on by my one and only mentor that someone
that comes along later may have no idea what my code is doing. So
comment. Even when it might be self-explanitory, comment anyway.
In my 40-year career as a programmer, I've more than once had that
someone who comes along later be myself.
I also apply what I call the Bus Principle. If you get hit by a bus
and killed, one of your colleagues is going to have to take over your
work. Give them a fighting chance with code comments, and maybe even
a design document for large or complex things.
I have noticed a lot of newer programmers these
days that say
(paraphrased): "Good code will explain itself" as a reason not to
comment. Mostly C++ and Java programmers.
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.
-Paul W.