

Don't waste your time commenting source code - tjogin
http://riyadsthoughts.blogspot.com/2011/01/dont-waste-your-time-commenting-source.html

======
RiderOfGiraffes
I've had this discussion, and thought I would share a specific example of one
case that to my mind highlights the issues.

I had some horrendously complex code to compute the two roots of a quadratic,
and someone came along and "tidied it up." They replaced my code with:

    
    
      delta = sqrt(b^2-4*a*c)
      a2 = 2*a
      x0 = (-b+delta)/a2
      x1 = (-b-delta)/a2
    

They were then horribly confused over why the tests started failing, the
check-in was broken, and all hell broke loose in the development branch.

He put it back and all was well, then came to ask me about it. I explained
about numerical stability, and all was well.

So with regards comments:

Pro: He would've known not to change the code, and it was complicated for a
reason.

Con: He wouldn't've come to me to discuss why it was a problem, and hence
wouldn't've learned about numerical stability.

Gripping hand: With a comment he would've known why, and the time wasted
changing the code, testing, investigating and putting it all back would've
been saved, and better spent learning about numerical stability, which he then
had to do anyway.

I'm in favor of the correct use of comments, and YMWV as to what that means.
Dogma is the enemy of true progress.

------
nupark
This argument is old and tired. Programming languages are rarely sufficiently
expressive as to document the nuances, guarantees, and expectations of a
particular block of code in the code itself. Type systems can help here, but
they alone are not sufficient.

An often stated rebuttal to the above is that the developer can comment the
"complicated bits", and save time by skipping it the rest of the time. This is
a flawed argument -- you don't _know_ if you need to write a comment for a
block of code until you've spent the time fully considering what needs to be
commented ... which takes just as long as writing a comment.

This holds doubly true for APIs. Any time that your future API clients spend
_reading your source code_ instead of skimming your documentation is wasted
time. Additionally, deriving guarantees and invariants from the source code
does not make them true -- the invariants could be changed in the future, as
there's nothing in the code to document _what should be_ , instead of _what
currently is._

"Comments are unnecessary" is just an excuse for lazy developers to be lazy,
and thus leverage externalities to reduce their upfront workload in exchange
for increasing the workload and complexity for the programmers that follow
them -- which may, in fact, be themselves.

~~~
icodestuff
I'm not sure I agree with all of that, especially the second paragraph. In my
experience, if your comments are English translations of code, you could
probably be writing the code more clearly. Exceptions are when you're using a
particularly hairy API, writing in Perl, building complex regular expressions,
or need to document side effects that are not otherwise clear.

Additionally, commenting every bit of the code, especially as you go along,
leaves one prone to forgetting the most important reason to comment:
explaining the rationale for what you're doing. Explaining the design
decisions in comments (and especially why you didn't do the alternative) is
invaluable, and much more accessible to a maintainer (such as oneself a few
months later) than an external design document.

------
mquander
This post is so trivial as to be flagworthy. If the author's coworkers ask him
about design decisions, invariants, or other minutiae regarding a piece of
code, does he explain it to them by writing more code? No? He uses natural
language? Then perhaps there are times when an inline natural language comment
is warranted. End of argument.

------
lhorie
Comment the why, not the what.

~~~
jameskilton
Exactly. There isn't a programming language in the world, and never will be,
that can explain the WHY of the code being written. I write tons of comments
explaining WHY I'm doing things so that 1) _I_ can understand what I did when
I come back to the code and 2) Other people can understand what I was thinking
and how the code fits into the greater whole.

I HATE code with no comments. And tests are not sufficient documentation,
though that's an argument for a different time.

~~~
elmomalmo
I've worked with a lot of legacy code over the years. I don't usually care
whether code has comments or not. Comments are a very poor way of expressing
semantics in code.

Usually, I'm looking for general readability and understandability. I'd much
rather see short, well-named classes and methods, well-named variables and
good unit tests before I see a single comment.

In the absence of clean, readable code, comments are probably a reasonable but
nevertheless inferior resort. I also agree that, sometimes, they 'why' of code
is often best expressed as comments.

~~~
nupark
_I've worked with a lot of legacy code over the years. I don't usually care
whether code has comments or not. Comments are a very poor way of expressing
semantics in code._

When working with legacy code that is not commented, how do you determine the
invariants of an API?

That is, how do you ensure that the change you're making will not break other
code? Do you have to scan the entire project, and any other projects that
depend on it?

Unit tests are often not sufficient here -- changing the invariants of an API
may not result in deterministic failure -- in fact, invariants often describe
requirements necessary for deterministic behavior.

------
rwmj
"A well-designed program uses classes and design patterns"

Ha ha ... also don't waste your time asking me for a job.

~~~
michaelcampbell
The only zealot as bad as the patterns zealot is the anti-(patterns zealot).
Which is of course, different from the (anti-patterns) zealot.

~~~
bostonpete
Even worse than that is the anti-(anti-(patterns zealot)).

------
frobozz
Every time this subject comes up, a pack of vociferous compulsory commenters
come out and start shouting about how desperately unprofessional it is not to
write comments.

I imagine, also, that a fair collection of idiots also start using it as an
excuse not to bother commenting their illegible code, but they seem to keep
quiet about it.

The author points out that "Sometimes you just need to leave a note", but that
doesn't stop people coming out and declaring it "the most retarded article
ever". These are people who can't tell the difference between "Never write
comments" and "Write clean code to avoid the need for comments".

Even as I write this, I imagine some of them bursting a blood vessel because
"You can't always avoid comments".

I agree, you can't. If (for example) you are authoring some workaround for a
counterintuitive 3rd party API, then yes, good commentary is important.

However, if you write short, well-named, DRY, SRP-obeying units, with well
named parameters and variables, and well-named, clear tests, then many of the
comments that you find in poorly written code simply aren't needed any more,
because they are there in the code itself.

------
deveren
I wouldn't work with a programmer who believed so strongly, against,
commenting source code. In the long run, it probably saves more time than it
"wastes". If someone develops proper habits writing sufficient comments, then
writing them becomes less of a hassle, and more of a better business practice.

Let's not forget that writing comments and notes is not unique to computer
programming. Most professions, law, medicine, must create notes, and comments
to understand the work at hand. Those who don't, or refuse are looked at as
lazy and unprofessional.

I don't want notes for every single line of code, but for sections of
complicated code comments are a must for ease debugging, or future
modifications.

------
michaelcampbell
I wish I could get to this point where I work, but his article presupposes a
couple things:

* You have tests.

* People write code to be readable.

Where I work, neither is the case. I try to write tests[1] for my stuff, and I
try to write clearly. But I have to comment what I'm doing since the libraries
and APIs I'm calling are so baroque and almost deliberately obfuscated, that I
have to comment what's going on if for no other reason than self defense.

[1] As a point of reference, in my current project we have something like 6 -
8 developers. Of the unit tests that exist, I've written 85% of them, and I'm
embarrassed at how few I've written.

------
maratd
Code should be beautiful. It should be expressive. It should be concise and
speak for itself. It should be both clear and obvious on the first glance. A
variable should be called what it is, not x or y. Once you've written a piece
of code, re-write it. Again and again, until it doesn't need comments and
speaks for itself. Once you've re-factored your code enough times and you feel
it can't get any better, then you can comment your code.

Many times developers write shitty code, put a stamp of "it works" on it and
then comment it, as if comments make it OK. Bullshit. Perfect code doesn't
need comments. We can't achieve perfection, but we can try.

------
herdcall
I tend to agree with the author, but there are times comments are the only way
to help the next guy looking at the code. Like when you're using workarounds.

E.g., I was recently writing for a JPA entity on Google App Engine where I
tried using a @PrePersist function to update a field. Turned out that GAE
won't call the @PrePersist unless a field is updated first...i.e., catch 22.

So, say as a workaround you add an artificial update to the field to null just
so your @PrePersist is called, what are the odds that the next guy reading the
code without a comment won't just delete that assignment thinking it's
unnecessary?

------
wladimir
I can't disagree more. Comments can help maintainability a lot.

It was always explained to me in this way: code describes _what_ is done,
comments describe _why_ it is done. Code cannot explain the second, and
comments should not explain the first.

------
hectavex
My semi-humorous response: [http://glassocean.net/riyad-mammadov-enterprise-
architect-sa...](http://glassocean.net/riyad-mammadov-enterprise-architect-
says-dont-waste-your-time-commenting-source-code/)

------
octal
I find that when you are developing an open source application, its rude to
not comment your code. Its the least you can do to help any other developers
willing to work on your project. I feel like its more inviting as well.

~~~
elmomalmo
I'd suggest that you help your fellow developers more by writing code that
needs fewer comments to make it understandable.

However, I agree that what you say is certainly true of APIs.

------
Ratufa
Maybe one reason to encourage comments in source code is not to waste the time
of good programmers who write clear code, but to help everyone who has to deal
with unclear code written by not-so-good programmers.

------
coolgeek
I hope that he spends some of his time not commenting to fix his js so that it
doesn't take 90 seconds to scroll down the page

------
ascendant
People that write this sort of "If you have to write comments your code sucks"
commentary are almost always the ones laying down new code. They're the
grizzled veterans who don't think about the junior guys that have to update
their code a year later and go "???" when they attempt to fix some subtle bug.

As I'm sure will be repeated over and over, comment the why, not the what or
the how.

