Excuses for not writing comments

As a professional programmer, I've seen a lot of excuses for poor code over the years. It's absolutely amazing the amount of passion and energy that goes into defending bad code. What's more amazing is that if half of that energy were directed into putting quality in the code, the problem would disappear.

Here's a list of some of the excuses I've encountered over the ages. See how many your management or co-workers have used. Maybe you've used a few yourself. I know I have, but I grew out of it. (Mostly.)

I don't have time to put in the comments.

This is the favorite excuse of the programmer in a hurry. You should write the comments before you write the program. That's so you can collect, focus and organize your thoughts so that your program is designed well.

The programmer in a hurry doesn't have time for planning. Or thinking for that matter. He wants to start coding now.

Think about it. Would you trust someone to build your house if he said, "I don't have time for blueprints, we're just going nailing together lumber for your house immediately." Think about what that house would look like. It would look like some of the programs we see today.

I'll put in the comments later.

This is a promise that's rarely fulfilled. As we've already discussed, comments should come first.

The trouble with putting in the comments later, is that the programmer frequently forgets what he wrote. Or he decides that large portions of his code are obvious and don't need comments. Or later never comes.

In any case, comments done later are almost always inadequate.

My code is self documenting, I don't need comments.

This is the excuse of someone who has never done maintenance programming. If they had to read some of the "self documenting" code of others they would never say this.

C and C++ are cryptic. They are languages designed for computers, not for communicating with people. English is a language designed for communicating with people and should be used for that purpose.

The specification is in my head.

A written specification is essential to producing a quality program. How can you tell if a program is doing what it's supposed to if there's no specification. Also the specification serves as a document to give to management and the potential users to let them know what's coming. That way any problems can be ironed out before the code is written.

True many programs as written without a specification. But most of these are written twice. The programmer writes the first version with no specification and little or no user input and gives it to the user community.

Much to his disappointment, rather than blessing it, the users bitch, bitch, bitch. The programmer blames this on "dumb users" who can't see the beauty of his program. Meanwhile the users are fighting to get productive work done with a piece of garbage programming.

The result is that a specification is written. It's along the lines of "everything that V1.0 has, but without the poor interface, and with a bunch of new features that will actually make the thing useful."

So the V2.0 has a specification. V1.0, which didn't will be thrown away.

If you write the specification first, you can help avoid throwing one away.

Our code quality is no worse than anyone else in the business.

This is a management excuse on why they don't give the programmers the resources, time, or support so they can do a quality job.

But quality pays. A good quality program can be 10 time smaller than a rush job. The result is that the quality work can be done faster, and will require much less maintenance that a rush job.

The response to any manager who spouts off this excuse is, "Do you want us to produce code at a cost the same as everybody else, or do you want us to do it cheaper?"

We don't have time for code reviews here.

Code reviews are the single best thing that can be done to eliminate bugs and improve coding quality. They not only make better programs, but the feedback makes for better programmers.

If you don't have time to do the code reviews, you shouldn't do the program. If you do half the job, you'll spend ten times as much on maintenance and technical support as you would if the job was done rights.

As you can see there are a lot of excuses out there. Most of them involve people too busy to do things right. In many companies there's a lot of pressure to get the product out. They never seem to have enough time. But as the old saying goes, "Why is there never enough time right, but always enough time to do it over?"