Game Development Reference
In-Depth Information
may look at the same block of code months later and not have a clue what the fix
was attempting to fix or what test case exposed the bug.
The solution to the problem of short-term programmer memories is comments, as
always, but comments in the late stages of development need some extra information
to be especially useful. Here
'
s an example of a late-stage comment structure we used
on the Microsoft projects:
if (CDisplay::m_iNumModals == 0)
{
// ET - 04/10/02 - Begin
// Jokerz #2107 - Close() here causes some errors,
// instead use Quit() as it allows the app to shutdown
// gracefully
Quit(); // Close();
// ET - 04/10/02 - End
}
The comment starts with the initials of the programmer and the date of the change.
The entire change is bracketed with the same thing, the only difference between the
two being a
keyword. If the change is a trivial one-liner with an
ultra-short explanation, the comment can sit on the previous line or out to the right.
The explanation of the change is preceded with the code name for the project and the
bug number that motivated the change. Code names are important because the bug
might exist in code shared between multiple projects, which might be in parallel
development or as a sequel. The explanation of the change follows, and where it
makes sense, the old code is left in but commented out.
“
begin
”
and
“
end
”
The Infamous [rez] Comments
Whenever I write a comment in a system that isn
'
t mine or make a change
that isn
Ido
the same thing for asserts and error messages that are on in the debug
builds. That way, people don
'
t straightforward, I always precede my comment with
“
[rez].
”
t have to hunt through the source control
system to find out who made a particular change; they can just come to
me and ask. This has worked really well for me, and if you
'
'
re working on
a project with multiple people, I suggest you do the same.
Most programmers will instantly observe that the source code repository should be
the designated keeper of all this trivia, and the code should be left clean. I respectfully
disagree. I think it belongs in both places. Code reads like a story, and if you are
constantly flipping from one application to another to find out what is going on, it
is quite likely you
'
ll miss the meaning of the change.
