Beginning Programmer’s Good Uses For Code Comments

Posted by: Rea Maor In: Programming - Monday, July 26th, 2010

This post over on Repeat Geek about 5 Types of Comments to Avoid Making in Your Code is good advice, and it rings true for anybody who slings variables – we’re all seen these many times.

But it reminds me, newbie programmers first starting out could use some guidance as to good types of comments to make in your code. So I thought I’d offer some of those.

Remember that code comments are for three types of audience: the casual user of open source just looking to quickly troubleshoot your program, the team programmer be it on an open source project or proprietary application, and you! Don’t forget that you, too, will someday have to maintain your own code and possibly have no clue what on earth you had in mind when you churned out this spaghetti.

Labeling blocks and sections. Probably the most obvious use of comments. It’s really quite simple: you’re just going to mark out where the main loop begins and ends, where you set up data structures for later use, parts that are functions, subroutines, and what-not, and other designated areas. This helps when you’re composing long blocks of something like…

if ((Brick[4][5]==Dot[1][0])&&(Zee[7]!=Foo[9][0][1])){Zee[7]=Foo[9][Dot[1][0]][1];}

if ((Brick[5][5]==Dot[1][1])&&(Zee[8]!=Foo[9][0][1])){Zee[8]=Foo[9][Dot[1][1]][1];}

if ((Brick[6][5]==Dot[1][2])&&(Zee[9]!=Foo[9][0][1])){Zee[9]=Foo[9][Dot[1][2]][1];}

…where it would help to break it up with a comment mapping out that you’re parsing column 5 of the Brick array.

Explaining what variables and arrays are used for. Sometimes you’re going to run across something like:

Bar[6][6]=

[[0][1][2][3][4][5]

[0][1][2][3][4][5]

[0][1][2][3][4][5]

[0][1][2][3][4][5]

[0][1][2][3][4][5]

[0][1][2][3][4][5]];

…and have no idea what the heck it’s supposed to do. When initializing arrays, it’s helpful to indicate what the array is for, why it had to be set up that way, and where in the program it might get used. Sometimes it even helps to include a little visual grid in the comments to help other programmers get a picture of what’s going on.

Indicating requirements and versions. It’s always helpful to document the conditions under which your program was first written, compiled, and run. For example, mention “First built on Slackware 10.2 system using gcc 3.5, libSDL 1.0, calling ImageMagick v2.7.1.” somewhere near the top of the file. That way, years from now when gcc has developed a new pointer bug (ha ha) that causes your program to crash on future systems, it will help a knowledgeable programmer to quickly diagnose what the problem is.

Explaining the non-obvious. This is helpful when you’re writing the next Duff’s Device. Whenever you just came up with something so fiendishly clever that it makes you giggle for five minutes just reading it over and over, that’s the time to document it and explain fully the how and why of it. And be careful of brittle constructions that could break later, anyway.

Diking out debugging blocks. This is the one exception to Repeat Geek’s rule #2, because debugging really never is obsolete. Say you have a Texas Hold’Em game; at some point during testing, you’ll find it useful to force certain hands rather than letting them happen randomly, in order to make sure that certain win conditions are recognized by the program. After you’re done with that little block, why not comment it out along with an explanation for how to use it later?

Explaining why you did things this way. That’s the number one question you’ll find yourself mumbling if you read somebody else’s code and you don’t have them right there to ask. Because you might have done the same thing in a different way, or know a better way, or not know this better way that they used. Remember, it’s OK to be a niovice in a language you’re using, but just explain that in the comments, you wrote this inefficient data structure because you didn’t know a shortcut at the time, and it works anyway.

You should also take into consideration the hosting environment in which the code that you produce will be hosted.


Related Posts:


Leave a Reply