Source Code Management Best Practices

Keep it fresh, keep it maintainable

Photo by Ilya Pavlov on Unsplash

When I zoom out on my over twenty years of professional experience in developing software, and running teams developing software, the one word that I center on is maintainability. The code you write has a primary job to “tell the computer what to do”, and it will do exactly that and nothing more. While many tools have been successful at launching “no-code” solutions, from WYSIWYG tools of the 1990s to more modern “vibe coding” (and hello, WordPress!), for the foreseeable future, humans will need to be able to read, understand, and maintain long-standing code whether or not they are the ones who wrote it in the first place.

The evolution of programming languages paints the history of making code more maintainable by humans, not always in a linear path. Ever since the discovery of using a transistor and binary code (1s and 0s) to instruct a a machine to “compute” and accomplish its assigned task, the goal has been to abstract that language into a way that humans can read, process, reason about and augment. Through layers of abstraction, from machine code to assembly to higher levels of abstraction (FORTRAN, Pascal, C) and into modern languages (Java, Python, Golang, Rust) and less-familiar paradigms like functional programming (LISP, Haskell, Elm) the goal has been to instruct the computer what to do in a way that other humans can evaluate it. Even today, when using modern AI coding tools like Cursor, Windsurf, or Warp, most of the examples shown these days produce the code that is being generated is this higher-level code and not directly machine code.

When this code is generated, it needs to be managed and ultimately versioned. Because this code needs human review, it needs to be maintained in a way that humans can reason about the differences. With this ability to reason, humans can set checkpoints at known-good points in history, and roll back if any changes are found objectionable. This also provides an opportunity to establish collaboration, as interoperable systems need a means for establishing a contract for that interoperability. If functionality changes, the ability to identify that change via a version number is crucial.

Source code management (SCM) tools have existed almost as long as programming languages themselves. Earliest tools were command-line based, and when graphical user interface (GUI) systems were introduced, graphical front-ends were added as well. There have been many different attempts at both centralized and distributed tools, ranging from the original SCCS, to CVS and Subversion (SVN), to ClearCase and SourceSafe, but the most popular tool today is git. Invented by Linus Torvalds, the original author and lead maintainer of of the Linux kernel that drives the operating system by the same name, which is used extensively across modern computing devices.

For the remainder of this post, we’ll presume that readers are already familiar with the basics of git. We’re going to get deep here, so if you’re not up on your git-fu, I’d suggest using git’s own gittutorial or one of these others from W3 or Atlassian before proceeding.