
Don't comment your code - craigkerstiens
http://version2beta.com/articles/dont-comment-your-code/
======
fdr
I don't like to strenuously object anything in general, but I'll make an
exception this time: this advice makes me burst a vessel every time I hear it,
because I must confess that the number of code bases I've seen that are
chronically over-commented with incorrect information that do more harm than
good approach zero. Most commonly, I think this sentiment is partially wishful
thinking, partially frustration of incorrect documentation, and partially with
code that is more convoluted than otherwise ideally realized (submit the
patch, if one can).

Such pleas are always accompanied by some example in a vacuum which requires
no justification for why a piece of code exists, including tricky branches
that required careful reasoning to catch corner cases that might go without
detection when breezing through doing maintenance or changing things. If
nothing else, comments provide a nice breathing space between even short
chapters of a function to help the eye track the code...much better than
cramming stuff into a symbol name and relying on guesswork.

Does this mean that the post contains bad information? No, not necessarily,
but for me, the headline and thesis do not follow from the otherwise
reasonable techniques detailed.

------
jholman
First of all, if comments lie, so do function names. So refactoring to replace
all your comments with function-names is a waste of time. The same goes for
variable names; the difference is that you were presumably going to have
variables in your code anyway.

More constructive commenting advice:

If your comments are supposed to explain what the code does, give a few extra
minutes to considering whether the code could be clearer (some tasks might
require complicated code that merits comments, but most tasks can be
accomplished with self-explanatory code).

On the other hand, sometimes there are external reasons, not enscapulated
within your code, why you must do something surprising. This unequivocally
merits comments. "I did this because of RFC #XYZ" or "Partner FooCorp needs
this bizarre format, see /global/path/to/spec", or "our data has such-and-such
a distribution, thus this surprising approach, which improves the 99th %ile
latency".

~~~
mrbrowning
Not only that, but in the last example in that section he replaces a fairly
short and readable expression with a function call. I don't see how this is
different than a comment in any meaningful way (except that it requires extra
lines of boilerplate and whitespace that don't lift any explanatory weight),
and unlike a comment it pollutes the call stack for no good reason.

~~~
hackinthebochs
The call stack is cheap, its your mental stack that you should be trying to
optimize for. Any label over a set of operations (even a single expression)
will reduce the mental load necessary to understand an operation, assuming its
reasonably named. Managing a stack is what computers are good at. Lets
optimize our code for how we can better comprehend it--at a consistent level
of abstraction with the fewest amount of level changes as possible.

~~~
mrbrowning
Oh, I wasn't trying to make a claim that this would result in any noticeable
performance degradation in the vast majority of cases, but as a means of
making code more understandable this particular example suffers in comparison
to a comment: less code is on the screen, it requires the reader's eye to jump
elsewhere, and again that particular expression is simple and about as easily
understood as the function name that replaced it. I think we agree on what to
prioritize in writing code, but I don't think that example in the article was
a good demonstration of those priorities in practice.

------
klibertp
Or, you know, learn to write useful comments already. I know it's hard, but
doable, really.

~~~
jlogsdon
Exactly this. Don't litter your code with comments, use them when they make
sense. For example, if you're doing something "against the grain" but have a
good reason: leave a comment explaining why.

~~~
qu4z-2
I quite liked the previous article we had "Comments are apologies" or
something. HN seemed to rail against it overall, but it makes sense to me.
It's sort of "Sorry, but this has to be this way because API <x> does thing
<y>". Or "This is a bit convoluted, but necessary because the naive way is too
slow." That doesn't have to be the literal text of the comments, but that's
the sort of mindset they should be written in, imo.

------
DanBC
I'm curious: Have people had a look at code they wrote ten years ago? Are they
glad it was uncommented, or would they have preferred comments, or were the
comments lousy?

When you're taking on someone else's project do comments help, or do they make
things more confusing?

~~~
qu4z-2
Well, I'm only 23 so any code I wrote ten years ago was hopelessly simple by
comparison to what I'm writing today. But to answer your question: In general
I found it over-commented, but it was simple enough that I could ignore the
comments and look at the code. I don't know how I'd feel looking back at my
code now.

------
informatimago
The rule was originally against comments of the kind:

    
    
        eggs:=eggs+1; (* increment eggs *)
    

All the other comments should be kept, and maitained synchronized with the
code.

Now like you may want to have some tools to track the link between
requirements, design and code (so that when requirements change you may know
what design decisions should be reviews and what parts of the code should
evolve, youl may want some tools to track the dependency between the code and
the comments and check their updated at the same time.

So I would suggest, instead of throwing the baby with the bathwater, to
imagine and implement the missing tools!

