Repository Usage

What is the purpose of a source code repository? In my limited experience, the source code repository has been central to every software engineer's workflow. It's such a fact of life that nobody asks that question anymore.

My guess is that a source code repository solves the following problem:

It's very hard to keep track of your files.

Perhaps this problem is just part of the more general problem of handling complexity in a software project. The use of source code repository relieves us of the responsibility of working with that kind of complexity. However, you may create additional complexity by making some of the following mistakes:

Using the source code repository as a workspace. Too many checkins often results in a cluttered source history. Unless there is some mechanism to manage these checkins- it will be difficult in the future to discern source code history. A general rule I use: Only checkin code once it has met some criteria for suitability- e.g. passed all unit tests (you might include that in your commit comment). Consider using a personal repository for more fine-grained revision management.

Not using the source code repository as a workspace. Too few checkins also has the tendency to obscure source history. However, usually 'too few' means none at all. It's better to checkin buggy code than not at all. Too few checkins force developers to rely upon the source code changes (not the comment history) to understand changes. A large quantity of source code changes in a single checkin is difficult to understand.

Not knowing how to use the repository. This is probably the biggest problem of all. Misuse usually follows. If you don't know how to use branches, tags and merging functionality of your source code repository, it will force you to use tactics that are far less efficient.

Leaving the repository in an inconsistent state. It's difficult to discern that any number of checkins are related unless they occur in the same commit. Ideally, each commit will thereafter leave the project in a workable state. This solves a number of problems when it becomes desirable to back out, or reapply source code changes.

Clutter in the repository. Clutter is defined thusly: unused code, unused files/tests, commented-out snippets, anything that isn't used- but "may be used later". By following a protective policy for unused source code, you are guaranteed to increase the complexity of your project. And that is exactly the enemy source control is meant to fight. Unused code is a bane for a few reasons:

• Because it exists in the source code repository, it is presumed to be 'tested' and 'solid' code. It's not.
• It will need to be re-understood and re-tested in order to be reused. Whatever time it took to type the code will almost invariably be re-spent testing and understanding it anew.
• It makes everything surrounding it more difficult to read and understand.

Finally some pet peeves:

• Duplicating revision history in the header of a code file. There is no guarantee this history is accurate. Unless the comments are long (which would make the history ungainly) they are invariably too short. And if they are too short, they don't explain enough to be useful.

Which leads me to my second pet peeve:

• Inappropriately short revision history comments. It would be lovely to understand the history of project simply by reading the revision history. But if the comments are limited in verbosity to "Bug fix" or "Wrong date calc" or "Algorithm rework", there isn't much use in them at all. Consider using complete sentences. Consider using statements that will be understood by someone who hasn't worked on the problem. Consider that you will promptly forget everything you did to the source code within 6 months.