Comments on: Why not to comment code

By: Bugfree.dk » Blog Archive » 2009 in retrospect

Bugfree.dk » Blog Archive » 2009 in retrospect — Mon, 28 Dec 2009 11:29:12 +0000

[...] Why not to comment code [...]

By: Olmeca

Olmeca — Tue, 18 Aug 2009 02:01:02 +0000

The thing is many programmers are not perfect. Though they know what they want the code to do, they don’t always get it right. This leads to bugs. Now to help the next programmer working on this code to find the bugs, of confirm the code is bugfree, it is necessary to also state in human language what the code was supposed to do. So yes, it is necessary to document your code, unless you’re the perfect programmer. I haven’t met one yet.

By: Veera

Veera — Mon, 17 Aug 2009 17:08:45 +0000

I always find it difficult to keep the comment in synch with the code. Whenever I need to change the code, the comments are also needs to be updated, thus doubling up my work.

By: To comment or not to comment, that’s the question « programming.torensma.net

Mon, 17 Aug 2009 14:01:17 +0000

[...] though I’m a great advocate of commenting code, there are those thank think commenting is not always a good thing. As stated in the linked article, we must differentiate between API documentation and normal, [...]

By: Simon Tewbi

Simon Tewbi — Mon, 17 Aug 2009 01:47:19 +0000

A useful quote: “Rules are for fools and the guidance of wise men.” – Sqn Ldr Dale “Spud” Murphy (no, not the mythical Murphy of Murphy’s Law fame).

I’m always wary of black and white statements – You must do this, you should never do that. And so it is with commenting code.

I agree that many (perhaps most?) comments are useless. However, comments are still useful for saying WHY you’re doing something in a particular way. To get around some obscure bug in someone else’s code, or to deal with a particular, not obvious, user case, for example. You can refactor code as much as you want but I don’t think it will explain to a maintenance coder (eg yourself a year down the track) why the code was originally written the way it has.

By: hacksoncode

hacksoncode — Sun, 16 Aug 2009 22:19:49 +0000

It’s very true that comments shouldn’t be needed to explain what your code is doing.

But that was never the point of comments. Comments are needed to explain *why* your code is doing what it’s doing.

By: Tobias Svensson

Tobias Svensson — Sun, 16 Aug 2009 18:20:22 +0000

I liked your article, even though many of your points are (hopefully) widely known. It reminded me of the ‘Comments’ section of the CodingStyle doc that Linus Torvalds wrote and is included in the documentation directory of the Linux kernel:

http://www.kernel.org/doc/Documentation/CodingStyle

Commenting, with regards to over-commenting and under-commenting, is a little bit like pulling shots of Espresso. If you run them too short, they taste very acidly and sour, if you run them too long they become an unpleasant bitterness