Notes on using a
Source Code Control System
aka
CVS
Bolo
Introduction
A source code control system is a wonderful resource.
It provides an organized way of tracking changes to the sys-
tem. It provides a method of doing version control, and
also a mechanism to do regression testing of the source code
itself. It has other benefits too, such as maintaining a
history that can be examined, instead of using ad-hoc meth-
ods such as comments and keeping old code fragments around.
At the same time, a source code control system is only
a tool. Used well it can provide all of the above advan-
tages. Used poorly, it can lose most of the benefits men-
tioned above, and in the end, provide only revisions of
individual files instead of a system-wide resource
Using a SCCS to your Advantage.
Here is list of guidelines to use or consider when com-
miting source changes to CVS. You've already heard some of
these, but I'm trying to collect them all in one place.
o Explain what you have done in your commit message.
When you do this, it puts the change into a context
that people can understand when they look at the
changes in the future. This also provides, through the
commit message mailings, a means of informing everyone
else on the project what you are doing. For example,
when fixing a bug, describe what the symptoms of the
bug where. Then describe what was going wrong in the
source code, aka why the bug happened. Then describe
how you fixed the problem.
o A SCCS provides a means of looking at the history of
something. For the most case, you don't need to pro-
vide your own history in the file by leaving old ver-
sions of the code commented or #ifdefed out. If you
are certain you want to make the change, just delete
the old code and be done with it. If you aren't cer-
tain you want to make the change, it is a good indica-
tion that your change isn't something that should be
checked in. Sometimes you want to leave a history in
the file, for example, to show all the "not quite
right" solutions so someone (including yourself)
doesn't just say "Aha!" to fix a problem, and just
chooses one of the already tried but wrong solutions.
These kinds of problems don't happen often, though.
o Don't checkin fixes for random bugs you have fixed as
part of another checkin. It becomes to difficult to
seperate the bug fix from the other work you have done.
Also, everyone else working on the project can benefit
from getting the bug fix now, instead of later. I rec-
ommend you keep a second workspace that you don't make
changes to. It's sole purpose is to be an up-to-date
workspace that you can apply bug fixes to. When you
find a bug and fix it, apply the fix to the bugfix
workspace, and check it in from there. Then update
your normal workspaces to get the bug fixed in them.
o If there is code that you are deactivating but want to
leave in the source file, do it gracefully. Provide
lots of info for others who are going to look at the
code and wonder what is up. Add a comment that spells
out why this code is here, what its status is, and why
it isn't being used normally. Do not comment code out.
Use C-preprocessor #if constructs to disable it. This
causes less diffs against the SCCS so you can actually
see what changes were made. Also a block comment is
used as a comment, not to mark out code, and is also
hard to spot. People assume comments are comments, not
inactivated code, and their eye tends to follow and
read the source that way. See the added guidelines for
#if use in the coding guidelines for some hints. Those
comments about what is broken should typically be
repeated in the CVS commit message so people know what
is going on.