I think programmers not commenting their code is an attribute of a programmer working on a project by themselves. It may also be related to the size of the project, though I seem to recall working on large projects at my old job and being told to code and forget about commenting.

Here at my company we have been working for ten months on an EJB/Servlet driven web application and all of our code is commented. Not everything is commented but every class has a Javadoc description and most methods are commented in a similar manner. And we have documentation for the system as a whole along with documentation for all the related parts, such as the data model and deployment instructions. We also go so far as to be quite descriptive when we check our changes into CVS.

Of course, I have also been a big fan of comments ever since they were forced on me by my lab TA's in first year computer science at UCalgary, something for which I will be forever grateful.

While working at UNLV I have come across several instances of people who did not comment their code due to a mistaken belief that such actions constituted job security. These individuals will demand a raise, "or else." They believe that since they are the only ones who will understand the code that they are indispensable. This is never the case. UNLV is just popping full of hotshot kids that will slave over a terminal to fix the code and comment it. Often times the code is even better than it used to be. As a side note, this behavior is not isolated to code. I have seen similar situations involving: electrical wiring, phone wiring, data wiring, network setup, and filing systems.

My personal experience with poorly commented code has been that many times you never expect that anyone else will ever be looking at it so you don't bother, or your comments are sparse and of the reminder variety. In fact I'm running into this right now with my company's intranet. It's been passed down to me from someone who is no longer with the company, and it's one giant hack; no comments, terrible naming sceme, cryptic string manipulation, four copies of the same file with names like file_test1, file_test2, etc and it's completely random which one is actually being used.

But he didn't do this out of spite, or because he thought he was the best coder in the world or something. He did it that way because he was lazy (or very busy, I'm not sure which) and didn't think he'd be passing it off to someone else. Also it's clear that he intended to rewrite much of it (some comments to that effect) but didn't get around to it.

Granted, this is poor practice, but the motive is completely different than the picture painted above.

Note: Ender02 may have been attempting to be funny, if so I apologize for my serious response.

Second Note: Ender02 msg'd me and informed me that the writeup was not intended to be serious. I hereby apologize for not getting the joke and being too uptight. I'm gonna leave my response though, just because that's still what I think about it.

In Extreme Programming the rule is basically not to comment. Instead, spend the time writing the code so that it is comprehensible in itself. After all, code is an expressive language, just like a natural language. In many ways it expresses what it does much better than a comment could. Some examples were cited in a legal brief I read referring to DeCSS that went something like,

  • netsalary = hourlyrate * 40 - taxvalue(hourlyrate, deductions);
  • "Set net salary for one week's work by finding gross salary from hourly rate, then subtracting taxes withheld"
Ok, that wasn't the example. I just made that up. But they had that kind of examples. And the point is that if you need to comment something, in a lot of cases you should rewrite it so you don't need to comment it, instead of commenting.

Not that I totally agree with Extreme Programming. But I understand where it is coming from on this.

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).

Log in or registerto write something here or to contact authors.