Contents  Introduction  Documentation??  Why Comment?  Documenting Code  Odds 'n Ends  Printable version

Odds ‘n Ends

In this section I’ll just mention a few things off the top of my head that really didn’t fit in with my other section topics.

Separators

There will be times when you’ll want to completely separate some sections of code from one another. I touched on this with the bounding box of slashes (/) but not in the actual program. Here are a few ideas:

//DEFINES//////////////////////////////////////////////////////////////////////////

or

//-------------------------------------Defines-----------------------------------//

or

///////////////////////////////////////////////////////////////////////////////////
//                                     Defines                                   //
///////////////////////////////////////////////////////////////////////////////////

Personally, I prefer the middle option. It looks the nicest. Of course, there are many more ways to do this.

Programmer Tags

Here’s another idea I got from my thread on GameDev. In a team effort where you have many people operating on the same source code, passing it around, changing it, etc. in the comments add a short tag identifying the programmer. For example:

// <DS>

////////////////////////////
// code and comments here //
////////////////////////////

// </DS>

Yes, it looks like HTML tags, but what’s wrong with that? Now everyone knows who edited which part of the program. I’ve never used this system myself, so I can’t recommend it. My only concern is things starting to get mixed up when another programmer modifies the code set in place by the former programmer and you end up with stuff like this:

// <DS, MM>

//////////
// code //
//////////

// </MM>
// <AO>

///////////////
// more code //
///////////////

// </DS, /AO>

I make the first iteration, then MM comes along and changes half of it, and then AO changes the second half. If you try this, make sure the system you develop takes into account things getting mixed up.

Self-Control (over commenting)

Yes, in this case, there can be too much of a good thing. I know this won’t be that much of a problem for most of you, since before reading this article you probably never commented at all that much anyway, but I feel impelled to dispense with a warning: Too many comments is bad. Well, maybe.

It ultimately boils down to your commenting style. If you have a clean style, then you can probably comment every single line and it would still look good. But if you get sloppy, too many comments will start to get in the way of the actual code. The purpose of comments is to make code easier to read, but if you use too many comments and don’t place them correctly, you’ll undermine your efforts by making the code harder to read because you can’t tell the difference between the code and the comments. And believe me, color coding will not make a difference.

Descriptive Variable Names

For all the lazy programmers out there (including me), here’s a way to decrease your commenting workload - using descriptive variable names. What a concept. For example, instead of using the variable z to hold a number that represents the current amount of money, why not try current_amt, or currentMoney?

The same rule applies to any type of name - function, structure, instance, etc. As long as the variable name can describe what it’s supposed to do, you don’t have to describe it yourself. Ain’t life grand?

Conclusion

I hope that this article has helped you decide on how to best comment your code to make other people’s lives easier. For all those reading this that have never commented before, I hope that you take to heart most (if not all) of what I said in here and get into the habit of commenting (it’ll impress the Boss, believe me).

The greatest challenge of writing this article was trying to tailor it to meet the individual needs of everyone who would be reading this article. Unfortunately, there is no sort of generic commenting style I could utilize for my examples, so I simply used my own. Whether or not you like my style is irrelevant - there are many other ways to get it done just as nicely. But I hope you at least consider some of what I did with the comments and apply it to your programs; I can guarantee a better look and feel. As a last note, I know some of what I said cannot be applied to everyday problems - there may be a time where one line of code does require a few lines of comments. All my "rules" were stated with a "simple case" scenario in mind.

So, if you have any questions or comments, please post them to this thread. Happy commenting.

gaiiden@hotmail.com

Special Thanks To: