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

Xtreme Programming

[thisisauniqueid]

Right. When XP-heads tell you not to comment your code because it's not Xtreme, tell them they're wrong.

Re:Gotta document that code...

[skraps]

1. It wasn't a straw man. Learn those vocabulary words before trying to use them!
2. Thank you for the compliment, but clearly it is you who are the leet haxor, and you haxor it in Fortran 90 no less.
3. My point was that your concerns over a 15-year-old compiler for a POS language should have no bearing on this discussion.