Source Control: Part 4 of How to Commission a Software Project
This source control article is part of the “How to Commission a Software Project” series.
Source Control as Pain
True story: In my college days I almost walked out of the computer engineering program because I despised source control. In my defense, the tools imposed upon us twenty years ago were a far cry from the time-saving masterpieces current developers have at their disposal. And I hated the entire idea of it.
Then, I joined a software engineering team. I wasn’t just a solo-cowboy-nerd in my dorm room anymore. Understanding what my teammates had done became critical. I needed to write up bugs. I needed to write up lots of bugs. Source control became something I could grin and bear.
Then, I had the pleasure of inheriting someone’s complete disaster of a codebase. After experiencing that low and returning to well-maintained, source-controlled code, I had really fallen in love. And not just in a gushy way. I recognized source control as a necessary beauty in the world of software development.
Another true story: Against all odds and in the year 2019 when asked to review a project that had been in development for nearly a year our team discovered exactly zero commits to source control. Through my experience, that’s roughly the nerd equivalent of Alex Honnold going out to free climb El Capitan (ref.) covered in Crisco. On a related note, there was also no formal documentation (see Requirements Gathering).
Policies, Parameters, and Methods
I’ll go ahead and assume (I think we have enough of an understanding to trust you) that you’ll have a source control policy in place. The next step is to put some parameters around it to make sure you make the most of it.
- Commit a lot. The devs should commit their source code anytime a singular, atomic feature has been completed.
- Comment elegantly. Each time the devs commit, the descriptions should be a helpful artifact for the discoverer. Debugging someone else’s code (or your own with enough time separation) is a grand forensic exercise. Care for your fellow developer (or your future self) and make it easy for them.
- Use branches frequently. Might your code break something? Are you working on a secret feature? Do you have a hotfix prod? Is it Taco Tuesday? All good reasons to branch. And there are more. Get comfortable branching and merging branches to win at source control.
- Use a service. There are plenty of good ones. Pick one that matches your use case for number of projects, number of users, bug tracking features, automations available, or whoever has the cutest website. But don’t let some random locally-stored git repository be your single point of failure. Even for a one-off bash script you use to text your mom on her birthday (don’t do that either – bad form).
As you’re reading this, I can only guess about who you are (unless you tell me). Some of these ideas may be old news to you – or maybe they’re so far out of your governance that this is a pile of nonsense. Or, this could be a helpful set of beginning guidelines. In any case, if you’ve read this far, you’re likely adjacent to someone who can either benefit from these methods or be validated by having known them all along.
Interested in getting help with code review or a source control policy?