Martin Polden

Keep your repository in shape

Following a discussion I had with some friends this weekend, I wanted to write down a few points I feel are important to maintain a clean and tidy code repository. The following points usually help ensure developer happiness (for me anyway). A few of these points may be taken for granted, but are included for completeness sake.

Use a DVCS

Use a DVCS like Git or Mercurial. I'm not going to argue about the advantages of using a proper DVCS over traditional version control like Subversion or CVS, as several people more knowledgeable than me have already done so.

The short story is that using distributed VCS is a superior way of working with code and you'll be a better and more effective programmer if you learn to use one.

Be vigilant about ignoring files

Prevent garbage from appearing in your repository by ignoring the most common clutter early on. Learn to love .gitignore or svn:ignore (but seriously, don't use SVN). Typical examples are

.class
.py[co]
.out

…and other build artifacts.

Do not version generated files (code or otherwise). This could for example be code generated from a database or from XML. After a clean build you should not have any unstaged files. Generated cruft will sooner or later be added and commited if it's not ignored. Even people who use git can be lazy and do:

git commit -a && git push

Single-step builds

Make your project build in a single step. After a checkout the developer should be able to build, test, bundle and package the entire application in a single step. The step should be completely independent of any local settings or software, and should not have dependencies other than a compiler and the build tool(s).

Bonus point: Your build server will love you. You do have one right?

Isolation

Make your application as independent as possible of its environment. Ideally a developer should be able to run and debug the complete application on his local machine. A common way to accomplish this is to make your application support multiple environments (e.g. "prod" and "dev"). This simplifies development, debugging, integration testing and deployment.

Your project is not your IDE

Do not version IDE-generated files or other artifacts from your tools. If you must keep them somewhere, put them in their own directory (like support/toolname) or somewhere that's not the root of the repository. If you're versioning files containing absolute paths to your home directory and other nonsense, you're doing it wrong and people will hate you.

Strive to make your project independent of the tools you use (e.g. IDE). It's not a given that everyone will use or even know the same tools as you do. As Pragmatic Programmer so nicely put it, "Keep Knowledge in Plain Text", and no, IDE-generated XML does not count as plain text.

Ending note: People who read Pragmatic Programmer love to work with people who have read Pragmatic Programmer. Be one of those people.

Date: 2012-03-05 Mon 18:56

Author: Martin Polden