
Comments should be sentences - henrik_w
http://nedbatchelder.com/blog/201401/comments_should_be_sentences.html
======
h2s
Never write comments that re-state the implementation.

    
    
        # Try to read the configuration file.
    

If this wasn't already obvious without the comment, then the code is a mess.
Tidy the code up instead of painting over the problem with comments.

~~~
aaronem
That's a rule to be applied with a bit of nuance. Some things, especially in
languages like Perl whose syntax already reads like a half-deliberate attempt
to force an obscurantist style on the programmer, can't be made really obvious
without doubling or tripling the length of the code in which they're
implemented, something which imposes its own cost in readability and
maintainability. In cases like that, it can be useful to add a few comment
lines which briefly restate what the code implements, as both an _aide-
memoire_ for the original developer, and a minimal but immediately accessible
answer to the question of "what the hell is this _doing?_ " on the part of
those who follow.

~~~
robinh
I agree wholeheartedly. The syntax doesn't even have to be extremely obscure,
it can be highly useful in lower-level languages such as C as well: Often, I
just want to get a quick idea of what the next big block of code is going to
do without having to read the entire block of code.

~~~
dougk16
In that case it's often (yea I know, not always) better to put that block in a
separate function, like readConfigurationFile() instead of "// This block
reads the configuration file.". I almost always treat the act of writing
comments as a signal that my code is a mess...although they're sort of a
necessary evil when you're down to crunch time.

~~~
henrik_w
I agree, that's an excellent reason to create a function/method. Reason 7,
self-documenting code: [http://henrikwarne.com/2013/08/31/7-ways-more-methods-
can-im...](http://henrikwarne.com/2013/08/31/7-ways-more-methods-can-improve-
your-program/) (but of course it doesn't mean that you _never_ need comments)

~~~
goblin89
I think it's said that you should document the "why" (as opposed to "what"),
which is relevant when you're using an unconventional approach or for some
other reason your code may not be understood immediately, or when business
logic is involved.

------
bjackman
I only started doing this recently. It occurred to me that I had some
conception in my subconscious that natural language punctuation wasn't
required in formal language code files. I think it may have simply been a
cognitive spill-over from the fact that variable names start with lower-case
characters.

Looking back, it's totally ridiculous that I would, in a professional setting,
put my name next to unpunctuated writing. Aside from being ugly and hard to
read, it's straight-up unprofessional.

------
cgrubb
As of 2 months ago Ned doesn't follow his own advice:

[https://github.com/nedbat/byterun/blob/master/byterun/execfi...](https://github.com/nedbat/byterun/blob/master/byterun/execfile.py)

~~~
shoo
[http://en.wikipedia.org/wiki/Tu_quoque](http://en.wikipedia.org/wiki/Tu_quoque)

~~~
cgrubb
[http://en.wikipedia.org/wiki/Straw_man](http://en.wikipedia.org/wiki/Straw_man)

------
shizzy0
Cue the self-documenting, we-don't-need-no-stinking-comments rabble rousers in
3, 2, 1...

AND that's one reason why we're not an actual profession, people.

~~~
diminoten
My paycheck begs to differ!

But really, comments are one way to mislead in code. If a comment is made that
incorrectly states the intent of code, it's undeniable that this is harmful to
the readability of the code.

~~~
shizzy0
What's pay got to do with it? See

[http://michaelochurch.wordpress.com/2012/11/18/programmers-d...](http://michaelochurch.wordpress.com/2012/11/18/programmers-
dont-need-a-union-we-need-a-profession/)

Comments may mislead yes, but that's a problem with any sufficiently
expressive language, and code is one such language: code can mislead. The
functionality required of the code may be only half-implemented, then that
code is misleading. That code may work for certain easy cases, but it may be
harmful to your understanding of what functionality is actually required.

It's easy to see why we prioritize code over comments, why we prioritize the
mechanisms over the specifications. It's because code can have some manner of
automatic verification, and we're too harried to look into the comments, to do
code review. Deadlines abound. We can't stop work and say, no, we can't do
this under these time constraints without sacrificing a minimum level of
quality, specifically because we're not treated like an actual profession with
the clout or the responsibility that comes with such a thing.

~~~
diminoten
We don't prioritize code over comments because it can be automatically tested,
we prioritize code over comments/spec because the code is what gets executed.

And _I_ can say "this can't be done under these time constraints" at my job.
If you can't, then _you 're_ not being taken seriously because of some other
reason, not because you're a programmer.

~~~
mannykannot
My previous comment ("If that's the way you work, then your employer has made
a mistake") was ambiguous, and actually illustrates a point regarding comments
(and documentation in general). Like that comment, the short verb phrases that
make up source code cannot always express the intent of the programmer
(extreme 'self-documenting code' advocates think otherwise, but their
experience with simple programs and algorithms doesn't generalize.) In such
cases, comments are a good way to explain a design issue that is not obvious.

Who cares about these things, which don't change the code? Anyone who needs to
understand the code, which includes anyone working on it, including its
original author - writing a brief explanation of a tricky point can help you
spot mistakes before you compile or test, or even before you write the code.
The goal is to produce correct code, not just code, and the one thing that is
faster than continuous testing is avoiding mistakes in the first place.

FWIW, I think the idea that comments need to be complete sentences is silly.
Sentences can be as wrong, ambiguous, misleading or uninformative as simple
phrases.

------
brudgers
Literate comments are as a gateway drug to literate programming.

~~~
cema
True. However, how useful literate programming is depends on a number of
factors, time often being the main limiting factor.

~~~
taeric
I've found tooling is the main limiting factor. Time certainly doesn't help,
but seeing as how I couldn't use literate programming while my colleagues use
their IDEs is ultimately what means I will be ditching it once I get help on
things.

~~~
cema
Yes, that too.

Speaking of which: any good tools for literate programming?

~~~
taeric
Emacs org-mode has been blowing me away lately. Don't know how well it can
scale up to a large project, sadly.

------
ams6110
A developer I used to know put it thus: "A comment is an apology." I never
asked him to explain that, but I guess he meant it's an apology that the code
itself is not self-explanatory.

Clear, even verbose commentary can be helpful. But where it often breaks down
is when the code is revisited, and the comments are not updated as well. So my
practice now is to use comments in early development to help me remember what
I was thinking in that bit of code, but then remove most of them during clean-
up and refactoring unless something particularly non-obvious is going on. It
makes future maintenance of the code less likely to diverge from the (usually
unmaintained) comments.

Good code review could help here: "Hey, the diff shows you changed six lines
of code in that function but the comments are the same, do they need to be
revised?" But I've never worked anywhere where EVERY commit was reviewed,
rather a sampling is selected for weekly review. that leaves a lot of
opportunity for things to get missed.

Bottom line: extensive comments can add to workload when fixing bugs or making
enhancements. So only use them when they really count.

~~~
tsiki
The programmer who doesn't change the documentation when changing the code is
usually the same one who doesn't change the function name when changing its
functionality. If a bad programmer is tweaking your code, it doesn't really
matter if the documentation is in the variable names or in the comments.

------
akkartik
Contrast PG's style, which had a deep influence on me:
[https://github.com/arclanguage/anarki/blob/master/arc.arc](https://github.com/arclanguage/anarki/blob/master/arc.arc).
There's something to be said for an aesthetic of conciseness that lets one
spend less time scrolling around and more time just _thinking_ about what's in
one's field of view. That includes stripping comments of unnecessary verbiage.

The article does make one good point: that when you add to a terse comment you
often have to add capitals and punctuation. But that is also often a signal to
me to ask why I need to switch from communicating a fact to creating a
narrative. Is the narrative really necessary? Often I find some way to
reorganize the code without needing to narrate it. Relevant is [http://steve-
yegge.blogspot.com/2008/02/portrait-of-n00b.htm...](http://steve-
yegge.blogspot.com/2008/02/portrait-of-n00b.html). (But I'm not claiming
everybody who uses complete sentences is a noob.)

------
anigbrowl
I like detailed comments myself, but this argument is hurt by taking them out
of their context - it would have been more instructive to examine different
styles of commenting to document a complex function or how they can help or
hinder structural understanding.

------
grantph
I usually start by writing comments first in plain English based on a
variation of psuedocode. That way I'm focused on process first without
distraction. Comments are the plan. Clearly articulated steps like any good
cookbook. Easy to translate into any language.

// 1\. Write plain English psuedocode.

// 2\. Translate into scary looking code blocks.

// 3\. If maintaining, remember to update comments first (goto Step 1, then
Step 2).

The irony is another developer once claimed that my code was generated by a
machine. Apparently it was too methodical to be human. Like that was some
excuse for him to write crappy code. Urgh! To be great at anything, you need
to have excellent communication skills!

------
huhtenberg
Comments should be meaningful. Whether they are sentences or a Morse code is
secondary.

------
sefk
I love the attention to detail Ned.

