Gamasutra is part of the Informa Tech Division of Informa PLC

This site is operated by a business or businesses owned by Informa PLC and all copyright resides with them. Informa PLC's registered office is 5 Howick Place, London SW1P 1WG. Registered in England and Wales. Number 8860726.


Gamasutra: The Art & Business of Making Gamesspacer
View All     RSS
May 23, 2019
arrowPress Releases








If you enjoy reading this site, you might also want to check out these UBM Tech sites:


 

Make Your Bed, Eat Your Veggies, and Comment Your Code

by Neil Gower on 07/17/09 05:35:00 am   Expert Blogs   Featured Blogs

8 comments Share on Twitter    RSS

The following blog post, unless otherwise noted, was written by a member of Gamasutra’s community.
The thoughts and opinions expressed are those of the writer and not Gamasutra or its parent company.

 

Every programmer knows they're supposed to document their code. Just like keeping your apartment clean though, documentation often gets put off until "later". Also like cleaning, it's easier to do documentation as you go, rather than in a big push at the end of the dev cycle. A pragmatic commenting style can go a long way to making this a reality. Below are some tips to make commenting less of a chore.

Agree on a format

To me, order and consistency make code look right. If you work this way too, it's a good idea to settle on a common format for your comments. A couple possibilities for functions:

//-----------------------------------------------------------------
/// YOUR COMMENTS HERE //-----------------------------------------------------------------

/**
 * ... OR YOUR COMMENTS HERE INSTEAD
 */

Both of these are doxygen compatible. The first has the nice property of indicating the maximum line length, which is good for consistency. Typing codeIt's a bit of a hassle to type, so you'll probably want to create a macro for it in your editor of choice.

The second format is easier to type, and less fussy about line lengths (good if you are also less fussy about such things). It's not quite as visually impactful, but good use of whitespace can fix that. Pick something that works for you, and stick to it.

Keep it simple

It's easy to get carried away when trying to come up with a coding standard. The trouble with getting too elaborate is if the standard creates too much work, the temptation to ignore it will be overwhelming. Short comments also minimize wasted effort when you change or delete a function.

My suggestion is that any standard should accept this as a valid comment:

/**
 * Sorts the objects in place in front-to-back order.
 */
void sortFrontToBack( SomeContainerClass& toSort )

The point here is that while you could add more detail, you shouldn't have to. A one-liner is much better than nothing at all.

Don't redundantly repeat yourself over and over again

You don't need to restate things that are clearly stated by the code. It's fair to assume that the reader of your code understands the programming language you're working in. Let's say you're documenting a function like this:

int getOrgreCount( Zone& queryZone )

The name of the function is obvious, don't put it in the comment. Explaining that the queryZone parameter is a reference to a Zone object, also redundant. Returns an int, redundant. Really, all you need to say here is something like:

/**
 * Returns the number of ogres in the queryZone, or -1 on error.
 */

On the other hand, if you're working in a loosey goosey language like Python, commenting on the expected type is a very handy thing to include in the docs.

Develop a mental checklist

Sometimes you stare at an undocumented function and think everything about it is so obvious that anything you write would be pedantic and useless. This happens a lot when the code is designed well to start with and uses informative names. To get past writer's block in these situations, develop a mental checklist of things that might be worth pointing out, such as:

  • Parameter descriptions. Do any of the parameters need explanation? Are only certain values allowed or disallowed?
  • Error conditions. What happens when something goes wrong? Does the function return error codes, raise exceptions, etc.? Does it always leave the program in a valid state?
  • Limitations. Are there cases that the current implementation doesn't handle?
  • Performance guidelines. Are there cases where the function is really slow? Are there things the caller can do to make it fast?
By running though a list like this, you'll rarely be at a loss for words.

These tips will hopefully encourage you to tackle documentation proactively. Documenting code is part of being an organized professional, but it doesn't have to be a big chore. Most of the time, we're not building public APIs that need exhaustive documentation. Just leave your teammates and future-you some useful notes about what's going on in the code, and you'll soon be reaping the benefits of documented code.


Related Jobs

Crystal Dynamics
Crystal Dynamics — Redwood City, California, United States
[05.22.19]

FX Artist
Hyper Hippo Games
Hyper Hippo Games — Kelowna, British Columbia, Canada
[05.22.19]

Software Developer - Unity
Wizards of the Coast
Wizards of the Coast — Renton, Washington, United States
[05.22.19]

Sr Lead Software Engineer - Arena
Wizards of the Coast
Wizards of the Coast — Renton, Washington, United States
[05.22.19]

Lead Software Engineer - Arena





Loading Comments

loader image