Programmers don't comment their source code. The vast majority of us are guilty of it, and there are a plethora of reasons why we do it. None of these reasons are good. Code should be commented. That's all there is to it. If nothing else, there ought to be a comment block at the top of the file explaining what the program/module does.
So, why don't programmers comment their code?
"I'm the greatest programmer ever!"
The programmer* foolishly believes that he is God's gift to software authoring. The individual in question thinks that his code is so good that any moron could understand it without comments. After all, good code is self-documenting, right? Wrong.
"I'll remember what it does and why I did it that way."
The programmer believes that his memory will never fail. He will always remember every line of every program he has ever written. He will also remember exactly why the solution was coded that way. Yeah, right.
"But I could be doing something important"
Programmers who utter this phrase come from two camps: those who define important as writing other code, attending peer reviews, etc, and those who define important as reading Slashdot, noding, playing videogames, etc. Neither of these is a good excuse to not comment, but I know which one I'd fire and which one I'd encourage to write more comments.
"I don't know how to explain that in English!"
I have a hard time believing this one. The programmer may very well work with a simplified syntax and grammar all day, but he wouldn't have earned that B.S. if he couldn't put words to paper. Write it down, and quit pretending all you're good for is writing code.
"I don't want anybody else to understand it!
This one is just mean. Congratualtions, you've done something wonderfully complex. That doesn't entitle you to keep your discovery to yourself. If nothing else, comment your creation so that you still understand it three years from now. Also, unless you want to be stuck maintaining and re-implementing that code forever, let everybody else in on the secret.
"I work alone."
That's great. You want to succeed, right? Just because you're a development team of one right now doesn't mean you will be forever. It's much easier to expand when your new hires can start being productive right away. And when your new hires are productive, you make more money. Win win.
"It's a pain in the ass!"
That's why we call it work. Programmers aren't special. They have to do the crappy parts of the job, too. The sooner you start, the sooner you'll be done, and your manager will finally shut up about commenting your code. And we all know what a happy manager means: good performance reviews and raises. Work is now and always will be a pain in the ass at times. Your job is not special. They're all like that.
"I'll never work on this after I'm done"
This is the quintessential rookie mistake. So you've finished your first project, and all feels right with the world. You're ready to move on, and you do. You get a couple more projects done, but then they start coming back to you. It's not because they're bad; it's because the user wants a feature added or your creation now needs to interface with this other program. The point is this: your instructors make you comment for a reason. You're going to need it in the workplace.
"If they don't understand it they can never fire me!"
Yes, they can. And they will as soon as you start demanding raises after refusing to comment code like your boss told you to. If you do find yourself in an environment where not commenting code is rewarded, leave. Find a better place to work. I know I wouldn't want to start working someplace and have to work on undocumented code all day.
"I've gotta get this done, so much to do, so much to do."
The programmer has geniunely tried to do what he believes is best for the company. He will never leave (or so he thinks), and nobody else will ever have to work on it. "I'll get back to it," they say. "I really have to meet this deadline," you'll hear. This case makes me sad because it means that the programming team is understaffed. If everything is an emergency and deadlines can't be met, don't leave code uncommented. Talk to your boss. He may not hire anybody new, but at least he will be cognizant of the problem.
"My code is self-documenting!"
That's probably not true unless you wrote it in COBOL. You may very well know that
$string = join('',reverse(split('',$string)));
just reverses your string, but how hard is it to insert
# Reverse the string
into your Perl file? Some things don't need to be commented, but complex algorithms are just that: complex. Document that which other programmers need to understand but probably won't at first glance.
"I'm lazy!"
So am I. That's why I comment code. I don't want to have to figure it all out again later. Think about it once. If it's commented, you'll never have to figure it out again because you've written down explanations of all the hard parts. It makes more work for everybody involved if you've got to figure out the problem again every time it comes up.
"It breaks my concentration!"
Mine, too. If you can't write comments as you go, write them at the end of a coding session. Good comments are good comments regardless of when they are written. Just don't let the task go for days (or weeks). It's much easier to comment something that is fresh in your mind.
"Upper management doesn't care about comments."
The vice president looks at the metrics supplied to him. These usually include things like lines of code, man hours spent, and tasks completed. Just because time spent commenting isn't reported doesn't mean it isn't important. The better you comment, the more productive you will be when you edit your code later. This will decrease your man hours spent and increase your number of tasks completed.
All of the above are lame excuses. Comment your code. Save yourself the time and energy of figuring it out again later. Programmers are lazy by nature, so why do we insist on doing the work twice?
DISCLAIMER: Some of these are meant to be funny. I sincerely hope you can determine which ones. But in all seriousness, comment your code. Even if you don't want to, do it for yourself. Your manager will be a lot happier if you don't fight about doing your job. And happy managers give better raises.
* I will be using the masculine singular pronouns because Engish offers no gender neutral pronoun, and I think s/he and his/her look and sound awkward. I mean no disrespect to female programmers (or any other females, for that matter).