Comments on: The comment of all comments

By: Freek Leemhuis

Freek Leemhuis — Wed, 25 Feb 2009 09:56:21 +0000

@Mark: I’m sure it is not the most original of posts, but I think it’s a point that needs to be made now and then, and I’m glad we agree on the subject

@Arne: I do agree with Fowler, in that you have to try to refactor the code so that comments are no longer required; if you can refactor in a manner that results in an implementation that is obvious and that expresses the intent, I’m sure you’ll agree that’s desirable. And I do think it is possible, there’s plenty of code that you can read and immediately grock the intent of the writer. Good naming of variables, methods and class names can express intent. Unit tests can express intent.
I do agree that this is not enough in some cases, where you might have specific reasons to choose a certain approach. I think we agree that in these cases comments are required.

By: Arne

Arne — Tue, 24 Feb 2009 22:39:11 +0000

The use of comments in code is always a point of discussion between software developers. In my opinion Martin Fowler is right by stating that comments in code *can* be a code smell, but I think he misses an important point by saying that you have to: ‘try to refactor the code so that any comment becomes superflouos’. Good code is indeed self-explaining concerning the syntax and semantical meaning of the code, but the *intention* of the code: the ‘why a certain approach or algorithm in code was chosen’, can never be read from code.

So in addition to this excellent post I would like to add a quote from the book ‘Code Complete’ of Steve McConnell: ‘write comments at the level of the code’s intent.

By: Mark

Mark — Fri, 20 Feb 2009 10:27:52 +0000

Nice to see I’m not the only one with this view… on my own blog (not posting a lot at the moment ) I posted something similar in July 2008.

http://www.markvandenbergh.com/archives/21/no-more-comments-in-your-code/

I didn’t came up the idea myself, but I read about it… and checked the code I was working on that day and I immediately found some good examples of redundant comments.

By: Adron

Adron — Mon, 15 Dec 2008 17:05:46 +0000

Great entry, I’m 100% in agreement with the no comment policy of Fowler and others. Hell, I’ve been following it for years unknowingly.

By: The comment of all comments | Tech Trend Watching

The comment of all comments | Tech Trend Watching — Sat, 13 Dec 2008 02:35:03 +0000

[...] Get more after the jump at .NET Developers Blog [...]

By: Head.SmackOnTable(); » Blog Archive » Commenting (And testing ScribeFire)

Thu, 11 Dec 2008 13:28:48 +0000

[...] The comment of all comments « Freekshow What does the line of comment add? Does it tell you anything that the code does not? Indeed not. Zero points. This kind of gratuitous comments is all too common, and if you have many of these, will you keep reading them? Will you not start to blank out the comments in your mind, thereby possibly missing the important comment that actually does explain a certain coding decision? [...]

By: Freek Leemhuis

Freek Leemhuis — Thu, 11 Dec 2008 11:46:11 +0000

Hey Frans, good catch. And here I am speaking of code reviews ….
I’ve amended it so as not to confuse the innocent readers. I failed trying to come up with a better joke though…

By: Frans Bouma

Frans Bouma — Thu, 11 Dec 2008 09:20:41 +0000

The return value comment on the GetMostPopularJokes routine, returns a ‘generic’ list of jokes, while the method returns a list of most popular jokes.

I know that ‘generic’ is referring to a generic list though one could read it as well as a reference to the mediocrity of the jokes returned