I'm the only front end engineer on my team and like most of us, I've got a crushing feature backlog.
Earlier this year I had the realization that if I left the project, it would either die or be completely re-written by the next guy. It wouldn't suffer this fate because I've written bad code, but because I'd been using the large feature backlog as an excuse to neglect all of the non-code parts of the project that enable developers to be effective.
The project in question is an application I helped conceive and something that has the potential to make the lives of our internal business customers much easier. Needless to say, I've got an emotional attachment to it and want to see it survive whether I'm working on it or not.
So, I set out to fix the situation. I did some research to try and figure out what best practices and tools I could use. After some time I was able to put together a list of things I needed to do in order to harden my project against turnover (or make on-boarding new teammates much easier).
Disclaimer
These articles are written to serve as a jumping off point for someone in a similar situation. They are intended as an entry level discussion. I give some tips on how I implemented the discussed concepts as I produced features, but those who are an on a mature team probably won't gain much from this series.
The List
- Git the most out of version control (see what I did there?)
- More better documentation
- Implement a coding style guide
- Easily reproducible environments
- Testing...ugh
- Utilize build tools
- Setup continuous integration
Version Control
“Any kind of practice that tracks and provides control over changes to source code” - Wikipedia
Most of us use or have at least heard of version control before. But for those that are new to the subject, its just a system of keeping track of the changes you've made to your code.
Version Control Systems
Software that helps track these changes are called Version Control Systems (VCS).
There are 3 major VCSs to be aware of. They share many of the same major features but have some significant implementation differences. I encourage you to try them all out and choose one that fits your way of thinking and meets your needs.
- Git
- Mercurial
- Team Foundation Server VCS
Git
Git is currently the most popular of the 3 due largely to its widespread adoption in the open source world. Most open source tooling around VCSs assumes that you're using Git. It has been described as the "MacGyver" of VCSs because it has lots of utility functions and there seem to be multiple ways of accomplishing the same thing.
Most of the online repository services support Git, including Github, Bitbucket, and Team Foundation Server.
Mercurial
Mercurial debuted around the same time as Git in 2005. It was a strong competitor to Git until around 2010 when Git seemed to gain critical mass. It has been described as the "James Bond" of VCSs because many people believe usage of it to be more elegant than Git.
The main online repository service that supports Mercurial is Bitbucket.
Team Foundation Server VCS
This is Microsoft's VCS. If your company is mainly a Microsoft shop, there's a good likelihood that you'll want to use TFS as it integrates nicely with all of the Visual Studio environments and tooling.
As you might expect, its only supported by TFS.
VCS Tools
There are many tools out there focused on providing a GUI for VCSs.
Some Git standouts are Tower, Github's Windows client & Github's Mac Client, and SourceTree.
Some Mercurial standouts are SourceTree and TortoiseHg.
TFS is tightly integrated into Visual Studio IDE.
My favorite is SourceTree because I can use it for my Git and Mercurial projects, but you should check them all out and choose the one that best fits you and your needs.
Issue Tracking
Many of the VCS services provide a way for developers and users to submit issues and discuss them. I won't get into issue tracking much here besides to say that many developers, even solo developers, find issue tracking to be a fantastic way of keeping track of required maintenance for their applications.
Commit Messages
Once you're using version control, one of the most important things you can do to help your team understand the changes happening on the project is to write good commit messages.
Good commit messages describe 3 things.
- The issue being fixed or feature being added
- The changes made and the rationale behind them
- Any side-effects the changes bring
Examples
Bad Commit Message
commit -m "Fixed a spinner bug."
Notice 2 things here.
Firstly, the message is incredibly vague. What spinner bug? Where is it? How'd you fix it?
Secondly, its written in the command line. Executing VCS commands from the command line is not necessarily a bad thing, however, committing from the command line makes it very hard to craft good messages.
Good Commit Message
From a VCS tool
Stops the spinner from showing on form A's "ok" button hover (#123)
Removes the event trigger that caused the spinner to show when the user hovers over the "ok" button.
As you can see, this message was written in a VCS tool. This allows you to format the message in a way that's conducive to writing good, informative commit messages. Some of the tools even allow you to write commit messages in markdown. Fancy!
You'll also notice how specific the first line is. It explains the issue being addressed and also where in the application you'd find the issue (Form A's "ok" button). It even has a reference to an issue number (the VCS you use may have a more integrated way of linking commits with issues).
The second paragraph explains what was done to address the issue. This is where you can get a bit more technical and where you'd go into rationale if necessary.
Branching
Branching is a feature of VCSs that allows you to make as many changes to your code as you want while still maintaining a version that is ready for your users. When you're done making changes, the VCS will assist you in "merging" all of your changes back into the main version.
The Theory
Take the following example:
http://www.gamasutra.com/db_area/images/feature/5900/image001.png
In this example there is a main development branch. A branch for Feature A is started, but before it is finished Feature B is started in its own branch. Likewise, before Feature B is finished, Feature C is started in its own branch. After that Feature B is finished and merged back into the main development branch, then Feature C, then finally Feature A.
The theory here is that at any point in developing Feature's A, B, or C the main development line could be put into production.
My Branching Scheme
The branching scheme I use is based off of a Mercurial plugin called Hg Flow which is also a built in feature in SourceTree. There exists a "Git Flow" as well, but I have little experience with it.
It looks a little something like this:
The heart of the repo is the development branch. It is the branch from which features are started and the branch that completed features join the herd. When a substantial feature set is finished, the development branch merges into the production branch.
Hg Flow and Git Flow have convenience functions to facilitate this including a "Start Feature" button that opens a new branch and even namespaces the feature with "feature/".
Conclusion
Version control is the most basic, yet most powerful thing you can do to start working in a team-friendly environment. Its easy to take shortcuts in branching workflow and in writing commit messages, and we all do it from time to time. However, creating and following VCS guidelines will enable your team and save you from unexpected headaches.