From: crossd@gmail.com (Dan Cross)
Subject: [TUHS] daemons are not to be exorcised
Date: Wed, 21 Mar 2018 14:04:05 -0400 [thread overview]
Message-ID: <CAEoi9W6_-2HLs=ywM42OtOG00GeBd=c0odxXhtsDcZhKy-n4Ew@mail.gmail.com> (raw)
In-Reply-To: <CABH=_VREt+Ay+T3wnGKvGyKn-7W7dn6K4vT7huBmX4a4GzjQKg@mail.gmail.com>
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>
next prev parent reply other threads:[~2018-03-21 18:04 UTC|newest]
Thread overview: 85+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-03-21 14:17 Noel Chiappa
2018-03-21 15:03 ` Clem Cole
2018-03-21 16:18 ` Arthur Krewat
2018-03-21 17:28 ` Paul Winalski
2018-03-21 17:33 ` George Michaelson
2018-03-21 17:50 ` Arthur Krewat
2018-03-21 19:49 ` A. P. Garcia
2018-03-21 19:37 ` Paul Winalski
2018-03-21 17:34 ` Larry McVoy
2018-03-22 2:24 ` Dave Horsfall
2018-03-21 17:39 ` WIlliam Cheswick
2018-03-21 17:52 ` Arthur Krewat
2018-03-21 17:56 ` Nemo
2018-03-21 18:01 ` Larry McVoy
2018-03-21 18:04 ` Dan Cross [this message]
2018-03-21 19:56 ` Clem Cole
2018-03-21 20:04 ` [TUHS] comments ( was daemons exorcised ) Earl Baugh
2018-03-21 20:18 ` Paul Winalski
2018-03-21 20:51 ` Ron Natalie
2018-03-21 20:13 ` [TUHS] daemons are not to be exorcised Paul Winalski
2018-03-21 20:28 ` [TUHS] Comments in early Unix systems Warren Toomey
2018-03-21 20:48 ` Ron Natalie
2018-03-21 22:18 ` William Corcoran
2018-03-21 23:02 ` Clem Cole
2018-03-22 1:31 ` Larry McVoy
2018-03-21 23:17 ` Arthur Krewat
2018-03-21 23:50 ` Larry McVoy
2018-03-22 0:55 ` Mike Markowski
2018-03-22 1:00 ` Larry McVoy
2018-03-21 23:45 ` Warner Losh
2018-03-22 0:31 ` Steve Johnson
2018-03-22 0:58 ` Andy Kosela
2018-03-22 1:27 ` Larry McVoy
2018-03-22 1:59 ` Bakul Shah
2018-03-22 14:46 ` Steve Simon
2018-03-22 15:22 ` ron minnich
2018-03-22 16:22 ` Ron Natalie
2018-03-22 16:32 ` arnold
2018-03-22 20:20 ` Lyndon Nerenberg
2018-03-22 16:33 ` Kurt H Maier
2018-03-23 1:31 ` Charles Anthony
-- strict thread matches above, loose matches on Subject: below --
2018-03-20 21:32 [TUHS] daemons are not to be exorcised Nelson H. F. Beebe
2018-03-20 1:26 A. P. Garcia
2018-03-20 1:40 ` Dave Horsfall
2018-03-20 1:47 ` maxigas
2018-03-20 4:23 ` Grant Taylor
2018-03-20 4:24 ` Steve Nickolas
2018-03-20 4:40 ` Grant Taylor
2018-03-20 5:19 ` A. P. Garcia
2018-03-21 2:31 ` Theodore Y. Ts'o
2018-03-21 3:20 ` Larry McVoy
2018-03-21 4:30 ` Warner Losh
2018-03-21 4:52 ` Grant Taylor
2018-03-21 9:16 ` Jaap Akkerhuis
2018-03-22 0:18 ` Grant Taylor
2018-03-22 0:22 ` Larry McVoy
2018-03-21 13:59 ` Clem Cole
2018-03-21 14:18 ` Paul Winalski
2018-03-21 15:15 ` Warner Losh
2018-03-21 15:45 ` Andy Kosela
2018-03-21 15:49 ` Warner Losh
2018-03-22 0:28 ` Grant Taylor
2018-03-20 6:32 ` Andy Kosela
2018-03-20 12:31 ` Nemo
2018-03-20 17:48 ` Paul Winalski
2018-03-20 17:56 ` George Michaelson
2018-03-20 18:04 ` Dan Cross
2018-03-20 18:24 ` Bakul Shah
2018-03-20 18:46 ` Clem Cole
2018-03-20 19:10 ` Bakul Shah
2018-03-20 19:55 ` Dan Cross
2018-03-20 19:56 ` Tim Bradshaw
2018-03-20 21:12 ` A. P. Garcia
2018-03-20 21:40 ` Andy Kosela
2018-03-21 6:32 ` Wesley Parish
2018-03-20 20:14 ` Warren Toomey
2018-03-20 20:25 ` Paul Winalski
2018-03-20 21:15 ` Clem Cole
2018-03-20 21:09 ` Clem Cole
2018-03-20 18:53 ` Toby Thain
2018-03-20 19:24 ` Nemo Nusquam
2018-03-21 12:10 ` emanuel stiebler
2018-03-25 19:56 ` emanuel stiebler
2018-03-26 9:44 ` George Michaelson
2018-03-26 12:38 ` emanuel stiebler
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to='CAEoi9W6_-2HLs=ywM42OtOG00GeBd=c0odxXhtsDcZhKy-n4Ew@mail.gmail.com' \
--to=crossd@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).