Commenting (in my experience) can help in determining what has to be done, like explaining a problem to a coworker can help in seeing the solution yourself. I think (I hope) most developers think first and then start coding. Writing comments can take place right in between. Not doing so but finding time to argue why comments aren’t neccessary to me seem a bit odd…

Hmmm, I think the code at the link you shown is poor. It’s all in C+ (note, not C++). Basically, it’s C-code masquerading as C++. If you code in C++, I say, use C++ idioms and learn how to code in C++ properly, not just in C with a couple object-orientated things floating around…

As for “self-documenting” code…well, here is a piece of the streams.cpp file:

https://sauerbraten.svn.sourceforge.net/svnroot/sauerbraten/src/shared/stream.cpp

void finishwriting()
{
if(!writing) return;
for(;;)
{
int err = zfile.avail_out > 0 ? deflate(&zfile, Z_FINISH) : Z_OK;
if(err != Z_OK && err != Z_STREAM_END) break;
flush();
if(err == Z_STREAM_END) break;
}
uchar trailer[8] =
{
crc&0xFF, (crc>>8)&0xFF, (crc>>16)&0xFF, (crc>>24)&0xFF,
zfile.total_in&0xFF, (zfile.total_in>>8)&0xFF, (zfile.total_in>>16)&0xFF, (zfile.total_in>>24)&0xFF
};
file->write(trailer, sizeof(trailer));
}

Yeah, completely clear and self-documenting. Not.

That’s reasonable enough except developers make mistakes from time to time, get distracted by the telephone, or whatever, and now we have a disagreement between the code and the comment. This is the worst kind of bug. Most bugs are easy to solve; this kind isn’t.

I’m not saying that code shouldn’t have comments in, but code *should* be self-documenting, and in my experience, all the best code is.

Here’s a link to one of my favourite examples of good code: very few comments, but very easy to grok.

https://sauerbraten.svn.sourceforge.net/svnroot/sauerbraten/src

I have decided to not work with ppl that do not document their code.

I had the pleasure to work with ppl who argued exactly like you said: we have speaking method names and the code explains itself. I was new to the programming language they used and I had a hard time figuring out what they were doing.

But then again, I had the pleasure to work with ppl who appreciate comments. A former employer mailed me just recently. They had to tweak something in an app that I wrote for them years ago. The employer said it was breeze thanks to my documentation.

If the system is well-documented when you get there, I *suspect* (aka no evidence to support this) that later developers will be a little more careful and respectful of the comments that are there, hopefully adding their own. After all, few people want to be the guy that screwed things up.

And I’ve been meaning to write on that quote for months…. alas. ;)

In my professional experience I’ve only been the originator of a project once – that is, the person who started writing the first code for any given project. That means that all my other projects were written by other people, even if I was adding new code. I wanted to avoid personal anecdote in the blog posting, but this is something I’ve experienced first hand. It’s critical that a code base have a good set of documentation for those who come after.

Someone once said “code as if the next guy to maintain your code is a homicidal maniac who knows where you live.” I think it’s a good rule to live by.

Depending on who you listen to, the development process itself is only 10-50% of the lifetime of that code. The rest of the time spent on it will be maintenance… quite often not done by you. So while you may be unlikely to see the longterm benefits of commenting, the people following after you will. And since you’re likely to follow after someone else elsewhere, it’s a handy process to start and share.

Keep it up Brandon.

From a practical standpoint, I don’t think faster delivery of a product constitutes a good reason to skimp on documentation or commenting where such is warranted. And, if you use evidence-based scheduling (http://joelonsoftware.com/items/2007/10/26.html) the time required to document and develop should actually end up inside your estimate of a ship date anyway.

Large block comments can be collapsed by most modern editors, so I’m not entirely convinced that block comments are bad for humans. If you use vim or something similar this might be an issue, but I’ve found that collapsing the comment is often the way to make the code more readable, once I understand what it’s supposed to do.

What happens when the comment doesn’t match the code? Is the code wrong or the comment? If you’re talking about understanding code, the only way you can truely do that is by reading it. A comment is only as useful as it is accurate and usually it’s not the glaring differences that are hardest to spot, it’s the really subtle ones. So if you’ve got to read the code anyway, you might as well make it readable. Viz. the code should be self-documenting.

I include comments to avoid ambiguities, like /* This line is duplicated here for a reason: don’t remove it. */. In a real example I’d explain what that reason is.

I also use them to point out where I think a weakness in the code (read: source of bugs) may occur, or where I’ve had to make comprismises. In short, comments are used to prop up weak code. The better the code is, the fewer comments it should require.

The worst kind of code to read is API code, which always has a big header above every function describing its signature and purpose. It’s great for the documentation parser, but not so much fun for the human trying to read the code.