Best Practices for Teams

My very first source control system was a red binder. No joke. I was learning Perl and I'd print out my scripts, three-hole punch them, slide them into my binder (most recent at the end of the binder), mark up the scripts with a pen and then apply my changes and test my work. Sounds quaint, doesn't it? What this allowed me to do was review my thinking over time. I could easily flip back and forth to see what I'd done previously, and perhaps more importantly, I could see my thinking as it progressed.

In the early days I commented EVERYTHING in my code: even my for loops were carefully documented. As my experience level progressed, I came to trust my ability to read code, and stopped documented the "how". You've probably heard the expression, "my code is so good, it documents itself"? The code will show you the "how", but it will never explain the "why" to you. And this, I think, is the sign of a mature developer: one who takes the time to explain the "why" as a preface to their code.

The same holds true for version control: your early commit messages will likely document "what" changed, but as you mature and become for comfortable with the system, you will get less anxious about using Git, the tasks will become mundane, and you will free yourself to write longer commit messages which explain the "why" of your work.

Teams of One

Solo projects, or projects where you are the sole developer. You are using version control to track your own changes, and perhaps are looking to expand your team and want to implement some structure now so that it's easier to work with others. It is assumed that no one else is working on your published repository, and that you don't need to worry about rebasing your work after it's been published.

Best practices

The following points are considered an absolute minimum for the solo developer. Deviate from this list at your own peril.

  1. Commit messages are descriptive, and never repeated. They contain both a description of what was changed and why the change was made.
  2. If you are working on a problem which has a few follow-up commits to fix minor issues, squash these minor changes into a single commit using git rebase -i.
  3. You tag releases according to when code was published, or shared with a client so that you may easily review highlights using git tag -a "tagname" -m "reason for tag".
  4. If you are extending another project, keep your own changes in a separate branch so that you can easily pull changes from the main project into your own work using git branch <branchname>.
  5. You use standards for everything that is arbitrary. For example: structure of a commit message; granularity of a commit; branch names; tag names. Document your standards in a README file which is embedded in the project.
  6. Where possible, use external, automated review tools. For example, Drupal has the coder module to check code against Drupal standards.

Teams of More than One

As soon as you start collaborating on a project, you will begin building on the best practice rules. Determine ahead of time how trust will be determined. Do you have test coverage? Peer review? Who is responsible for QA?

Best Practices

In addition to the best practices listed for "Teams of One", you should now add the following practices to your routine.

  1. All changes are documented first via a ticketing system of some kind. Each change is implemented in its own branch. Branches are named according to the ticket number, and a brief description. for example: 231-add_thumbnail_blog_posts.
  2. The first word of a commit message always references the ticket number in square brackets. For example: [#231] Added thumbnails to blog posts. The square brackets prevent the commit message from being interpreted as a comment (and thus hidden from git log).


As soon as you introduce a review process, you introduce the concept of a gate keeper. This gate keeper might be automated (Jenkins running test suites), or manual (a QA team, or peer review). You may have several review points: e.g. peer review before the ticket is closed, and the a second QA review of all tickets completed in a given sprint. Each time you delay a change from being deployed, you are introducing a potential for code to get out of sync as other developers continue to work on new problems.

How you deal with the review and collation process will inform your branching strategy.