Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Don't waste your time commenting source code

riyadsthoughts.blogspot.com

Post reply on HN
Print view View original

1–10 of 25 posts

Re: Don't waste your time commenting source code

#3

Post by 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.

Re: Don't waste your time commenting source code

#4

Post by 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.

Re: Don't waste your time commenting source code

#5

Post by 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?

Re: Don't waste your time commenting source code

#6

Post by jameskilton »

lhorie wrote: post #2

Comment the why, not the what.

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.

Re: Don't waste your time commenting source code

#7

Post by 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.

Re: Don't waste your time commenting source code

#10

Post by 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.

Post reply on HN