Comments are More Important than Code

CowboyRobot writes "I was going through some code from 2002, frustrated at the lack of comments, cursing the moron who put this spaghetti together, only to realize later that I was the moron who had written it. An essay titled Comments Are More Important Than Code goes through the arguments that seem obvious only in hindsight - that 'self-documenting' code is good but not enough, that we should be able to write code based on good documentation, not the other way around, and that the thing that separates human-written code from computer-generated code is that our stuff is readable to future programmers. But I go through this argument with my colleagues, who say that using short, descriptive variable names 'should' be enough as long as the code is well-organized. Who's right?"

Comments

Re:Comments Should Reflect Intent

[NitsujTPU]

class Gorilla
{
public boolean isMagilla()
{
return true;
}
};

Re:Comments Should Reflect Intent

[Brandybuck]

Comments can be good, but a lack of comments is ALWAYS bad.

Re:Comments Should Reflect Intent

[NitsujTPU]

Redundant again... someone has it out for me.

Cripes, I stuck a joke in there.

After 22 years of coding...

[coolgeek]

I think it's safe to say comments are for the benefit of those who have not assimilated their language, their APIs, etc. Sure, documenting interfaces is essential as well as how certain data structures are used as well as how certain events can interact.

Conversely though, most of the other comments I have seen are completely superfluous and only enhance the understanding of the uninitiated.

Re:Top Ten Code Comment Do's List

[jlechem]

Man mod this guy up. This is a trick I learned a long time ago when I first started writing serious code in college. Doing this forces you to think through the steps of the algorothm/process your using. For me it makes it easier when I write the actual code to have these predefined steps already in place.