Types of Comments to Avoid Making when Programming

If behavior is strange, you want to know if it was expected to be that way, and why. You can use the developer's line of reasoning to prioritize. If you understand the conditions that brought the hack, you are better prepared to maintain the code.

The article suggests that most problems should just be fixed right away, instead of leaving "someday" comments. But, a few weeks of maintaining a large code base will cure anyone of this belief. Not everything can be fixed right away, for many reasons:

- Maybe there isn't time, due to pressure to complete X or Y.

- Maybe it's risky to just hack in the first solution that pops into your head, and you need time to come up with the right fix.

- Code bases can be very complicated. You're not usually working on your own brilliant creations, you're working on things that many other people did, and some of them had no clue. You are tinkering with an engine you didn't design, and you have to be careful.

- The bug might actually be important in the short-term. One of the evil realities of large code bases is that "bugward-compatibility" can matter, and "fixing" something may cause more immediate problems than it solves.

And "just fix it" for #5 is ideal, sure, but on any significant project there are likely to be "temporary" workarounds that persist for a while and should be noted (along with who to ask for details), e.g. because they're workarounds for a third-party bug that you're waiting to be fixed, or new functionality hooks waiting on some module that isn't done yet.

#5 comments are very useful when writing code because they allow you to remain focused on the particular functionality that you are trying to implement while ensuring that you don't ignore things that are important in the grand scheme of things but are not particularly important to do at this moment (and certainly not important enough to be permitted to distract you from focusing on what you are accomplishing right now). TODO comments let you write the skeleton of your code and mark the places where you know you need to come back later to do more mundane tasks like carefully considering what kinds of errors may occur and what sort of exceptions should be thrown or caught or thinking about whether or not something should be written to a log. TODO comments are the bedrock of getting things done while still managing to not forget about details.

However, I agree that #1 and #5 comments should not persist in production code. They are little "under construction" signs that should be removed when the code is solid.

The code was mostly entirely uncommented. In a few files, it was heavily commented, but often strangely... such as allegorical comments relating the code to a magic act ("and now we shall make the volunteer vanish into thin air!"), or quotes from movies that loosely described the code.

I've seen a lot of 2 in shell scripts that aren't under version control, and it's necessary. Though I once slimmed a script I didn't write down from about 1000 to 200 where a lot of that was comments and duplicated functions. (As in, the script would repeatedly define the same function with a different name and a different path hard-coded in, and then call each function in turn.)

The only one that I would say is in a class you legitimately should never do is #3, but no one would ever write that comment except to be flippant.

So sometimes that's okay.

Number 2 is also sometimes needed. But instead of commenting it like C++, we #ifdef it 0. It's probably wrong, but if you are working in "foreign waters" and you are not sure, old code like this might give some clues (this is assuming the code base is not really that good, and not much documentation either).

3 is awfull, but acceptable for standard libraries, or code that is really trying to be specific about something.

4 is also okay, but not like this - it could be: "// TODO: Jimmie's bsp file (quake bsp) wasn't working due to some new lumps introduced. Temporarily fixed, needs proper one. Also a coder introduced a TODO macro, that in Visual Studio actually prints out TODO when it's building the app.

Seen 5, and it's reasonable - for example: "Due to short deadline, blah blah blah". Again if possible add the TODO macro, so it's fixed later.

For game development for example - It's almost always more important to ship on time, rather than to have some well commented code. I wish that was the case, but I haven't found a studio where this is really done - maybe engine, sdk, framework, library developers do that.

What does bug me are: 1) Out of date comments. I hate when comments say one thing, but clearly the code has changed and the code now does something else.

2) Comments lacking context. I've seen things like, "exception only occurs when persisted"... what's persisted? I don't see how any exception occurs here. It's until an hour later can I find what they're referring to.

Now I just seem to write comments where the reasoning isn't obvious. Which is often, but not that often. And they can be of all the kinds described in this article.

If this is the best knowledge you have of the requirements, then by all means document it. It should be documented in emails to your boss (along with your failed attempts at getting better requirements,) but adding a comment in the code can also be helpful. Maintenance programmers tend to assume that there's some valid, if depressing, reason the code is the way it is, and it's nice to let them know that you didn't have any good reason for doing it the way you did.

Although it may seem that I'm describing why and not what, a couple of weeks later I would be looking at that piece of code and wondering what's the purpose of that piece of code. :|

This happens quite a bit when pseudo-coding in the code and these comments get left behind. However, sometimes these green comments are good to quickly scan through blocks of code.

I have seen countless shops where valuable history was lost because it was stored on someone's c: drive, a network drive, or some repository that failed to survive some kind of migration. And even if these other files (digital or paper) did survive, chances are that the programmer that needed to see them never did anyway.

Good shops practice keeping audit trails in the source code. This means good commenting. Which means good code review and quality control.

I recently came across a single piece of code that had been changed back and forth 6 times in the previous 2 years. The comments looked something like:

  * jeo 02/11/09 Use Ship Date, not Book Date per Sarah in Sales
  * jrm 04/15/09 Use Book Date to make military contracts balance
  * msl 08/24/09 Use Ship Date per Joe in Ops (military no longer active)
  * jrm 12/13/09 Use Book Date per Rick Smith to prepare for new contracts
  * jrm 02/14/10 Use Ship Date per Rick Smith after Ops meeting
  * jrm 05/25/10 Use Book Date per Rick Smith until Q3 migration

Sure it's a pain it the ass to maintain this, but it immediately provides the needed background to the person who needs it, when he needs, where he's already working. For critical projects with confused users (what isn't), the alternative is usually much more work.