Comments on: // comments considered harmful

By: Linkschleuder (7) – Die Welt ist gar nicht so.

Linkschleuder (7) – Die Welt ist gar nicht so. — Mon, 04 Jan 2010 18:01:06 +0000

[...] // comments considered harmful [...]

By: David Humphrey

David Humphrey — Mon, 14 Dec 2009 14:35:05 +0000

Ryan, your statement assumes “the author,” which is precisely the problem my post is addressing, namely, that as code ages and is maintained, multiple authors get involved, and whatever the intent of the original, unless the comments are kept in sync with the code (they never are), those two sentences will mislead more than help. If code and comments are kept in sync, I’m all for good comments. My issues is that they so often aren’t, and worse, there is no way to tell whether they are in sync simply by reading them: the only way to know what you’re looking at is to compare the code. As such, I recommend starting there.

By: Ryan

Ryan — Mon, 14 Dec 2009 13:37:19 +0000

Knowing what an author thinks a function does and why that action is necessary is information often not present in the bare code. I’ll take a sentence or two of comments revealing those intentions and motivations every time!

By: Ben Hearsum

Ben Hearsum — Tue, 01 Dec 2009 21:20:23 +0000

I can definitely see where you’re coming from, but I can’t fully agree with your conclusion. However, if you’re like me, and prefer incessantly commenting your code, you need to be just as incessant about keeping those comments, docstrings, and usage messages up to date.

If you can’t commit to doing that, you certainly are better off without comments IMHO.

By: Andrew Sutherland

Andrew Sutherland — Sat, 28 Nov 2009 19:27:18 +0000

It sounds like your beef is with comments that aren’t maintained to the same level as the code the comments document/contextualize.

A better post subject might be “tests before comments”. A slightly more inflammatory variant would tack on “especially if you do a crappy job of maintaining your code”.