A few tips for source code versioning (do not drive your co-workers mad)

Source control management (SCM) is a technical matter as well as a good practice matter. Here is a small list of tips that I have found quite useful in practice.

A good commit is like a good paper:

• It starts with an evocative title. Ok, there is no title in SCM but there are comments provided while committing. If your SCM comment is not clear, then how do you expect your co-workers to keep track of what you are doing? A good title takes time and so does a good SCM comment. Do not rush your commit omitting the SCM comment.

• It has a clear self-contained content and focus. If you start working on many different files, you may end-up with a large commit covering many unrelated aspect of your software. Such a commit is hard to read for your coworkers because there is no focus. A lot of things are going on but nobody can really tell what did change and what did not.

• It goes right to the point: Insignificant elements are left outside the scope of the article. Do not commit a file if the changes have no purpose whatsoever. Such situations arise easily when you’ve just added or removed a few blank lines.

• The SCM comment is your title, eventually your headline, but it’s definitively not the content of your paper. In particular, do not use the SCM comment to raise questions or ideas. Those elements must be handled directly in body of your commit, i.e. the committed files themselves. The SCM comments will be quickly lost in the SCM history, but the ideas/suggestions must stay until implemented or discarded.