Comments on: Comments Unhelpful http://eraserhead.net/2009/03/comments-unhelpful/ Jason Felice's blog Thu, 07 Jan 2010 12:14:31 +0000 http://wordpress.org/?v=2.9.2 hourly 1 By: //FIXME » Rules for Commenting http://eraserhead.net/2009/03/comments-unhelpful/comment-page-1/#comment-2853 //FIXME » Rules for Commenting Wed, 30 Dec 2009 20:13:52 +0000 http://eraserhead.net/?p=32#comment-2853 [...] been a little while since I wrote Comments Unhelpful, and two recent events bring me back to the topic. The first event is discussion brought up by a [...] [...] been a little while since I wrote Comments Unhelpful, and two recent events bring me back to the topic. The first event is discussion brought up by a [...]

]]> By: Mark W. "catfood" Schumann http://eraserhead.net/2009/03/comments-unhelpful/comment-page-1/#comment-1921 Mark W. "catfood" Schumann Wed, 23 Sep 2009 20:45:59 +0000 http://eraserhead.net/?p=32#comment-1921 Another rule of thumb: clear code, including well-thought-out identifiers, tells you *what* it does. Comments tell you *why* it does it. I'm going to quibble slightly with point #3. It can be useful to have the "instant version history" of /recently/ commented-out code when making changes nearby. Wouldn't it be cool if IDEs showed a recent-change history when you hover over a method or block? Another rule of thumb: clear code, including well-thought-out identifiers, tells you *what* it does. Comments tell you *why* it does it.

I’m going to quibble slightly with point #3. It can be useful to have the “instant version history” of /recently/ commented-out code when making changes nearby. Wouldn’t it be cool if IDEs showed a recent-change history when you hover over a method or block?

]]> By: Austin http://eraserhead.net/2009/03/comments-unhelpful/comment-page-1/#comment-1454 Austin Sat, 06 Jun 2009 02:48:30 +0000 http://eraserhead.net/?p=32#comment-1454 I disagree with some of these; comments that explain the next line of code are nice because they help you understand what you were thinking. If you are more comfortable reading english than code ( which some programmers are ) then it is much easier to wrap your head around what the point was. It's also nice to come across when you are maintaining code that someone else wrote. Restatements of well named objects are good for the reasons above; also the best named object still is an object name, whereas a good sentence is a good sentence regardless. Comments with wanderlust are also helpful for making pointing out things along the way; like a rambling tour guide of sorts. Finally, restatement of constants also helps explain what intention the programmer had for them. Honestly I can't tell the difference between the good and bad; they both tell you how long the delay is supposed to be. The others I definitely agree are useless. I disagree with some of these; comments that explain the next line of code are nice because they help you understand what you were thinking. If you are more comfortable reading english than code ( which some programmers are ) then it is much easier to wrap your head around what the point was. It’s also nice to come across when you are maintaining code that someone else wrote.

Restatements of well named objects are good for the reasons above; also the best named object still is an object name, whereas a good sentence is a good sentence regardless.

Comments with wanderlust are also helpful for making pointing out things along the way; like a rambling tour guide of sorts.

Finally, restatement of constants also helps explain what intention the programmer had for them. Honestly I can’t tell the difference between the good and bad; they both tell you how long the delay is supposed to be.

The others I definitely agree are useless.

]]> By: Mark W. "catfood" Schumann http://eraserhead.net/2009/03/comments-unhelpful/comment-page-1/#comment-210 Mark W. "catfood" Schumann Wed, 15 Apr 2009 02:28:56 +0000 http://eraserhead.net/?p=32#comment-210 Rule of thumb: you probably need to comment your data structures more than your code. A four-dimensional array is a lot harder to understand without comments than a four-level nested loop. And yes, I've had to maintain four-dimensional arrays. That had no comments. Rule of thumb: you probably need to comment your data structures more than your code. A four-dimensional array is a lot harder to understand without comments than a four-level nested loop.

And yes, I’ve had to maintain four-dimensional arrays. That had no comments.

]]>