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

And this, my friends, is why offshore outsourcing

[melted]

And this, my friends, is one of the reasons why offshore outsourcing is doomed. You understand comments are important. For people in India schedule is far more important than comments. So they'll cut&paste shit all over the place and leave it uncommented. If you happen to have to work with it, your hair will turn gray pretty quickly.

Re:Opinion...

[duhasteifersucht]

Or you could just be smart enough to know what the code does without the comments? tool

Re:Gotta document that code...

[Anonymous Coward]

Of course you don't understand it. You don't know the language. That you chose to pick on the ?: operator and pointer arithmetic proves that you're a C novice. If you somehow manage to keep your job for more than three months then you'll probably have picked up enough to stay on... And in a year or two when you know the language then some cocksure little piece of shit who thinks he knows everything because he just got out of college having carried a 2.6gpa (and never did his coursework) is going to whine at you about these things being too hard to understand. And you'll pick up your copy of K&R smack him across the forehead hard enough to leave a bleeding gash, and then in two years he'll pick up his copy and smite his own n00b and the cycle will continue.

Seriously? Get a fucking clue. Get yourself a copy of K&R. Read it. Understand it. Once you think you understand it get yourself a copy of "Enough rope to shoot yourself in the foot" and prove it to yourself by reading it without whining about people using the language the way it is supposed to be used. There is no reason an entire development team should give itself a lobotomy just so a jew junior programmers and interns can understand parts of the codebase they should realisticaly not be touching anyways.

As a fun side project get yourself a microcontroller and write some assembly programs for it so you understand why C works the way it does. Good luck. I hope you make the grade.

In Soviet Russia...

[doxology]

Code comments on you!