Don't waste your time commenting source code

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.

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.

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.

Comment the why, not the what.

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

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

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.

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.

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.

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.

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?

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.

My semi-humorous response: http://glassocean.net/riyad-mammadov-enterprise-architect-sa...

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.

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.

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

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.