A Beginner’s Guide to GitHub Repo Hygiene

It’s 2020. If you’re like me, you’ve been washing your hands with obsessive frequency.

The concept of hygiene for health has been at the forefront of public consciousness all year (thanks, COVID!) — but I’m a beginner software engineer, so I’ve also been thinking about hygiene in a different context: the cleanliness, accessibility, and maintainability of my GitHub repos.

What is repo hygiene, and why do I care?

GitHub serves two primary purposes: it’s a platform for hosting version-controlled Git repositories, and it eases collaboration and code-sharing amongst developers. Good hygiene for GitHub repos means keeping your repos organized, consistently and accurately labelled, and rich with contextual information.

Perhaps you want to keep organized records of your code repos for yourself. Your future self will certainly thank you. Maybe you want to give other developers the chance to better understand and potentially work with your code, whether you’re sharing an open-source project or collaborating privately with team members. If you’re hoping to get paid for your software engineering work, it’s likely that you’re looking to make a good impression on recruiters who will want to see that you understand not just how to write code, but how to organize your work and optimize it for collaborative settings.

Whatever your motivations for keeping your repos squeaky clean, the return on investment for GitHub hygiene is impressive.

Here, I’ll focus on two key elements of GitHub repo hygiene: READMEs, and Git commit messages.

READMEs

We know we shouldn’t judge books by their covers, but it’s human nature to do so — a beautiful, well-designed book jacket with an intriguing blurb is likely to grab your attention, while a plain cover with a non-descriptive title doesn’t stand out.

The latter is like code that isn’t accompanied by a README. First impressions matter, and READMEs are usually the first files that you see when you open a repository on GitHub. Sure, the rest of the code in the repo can speak for itself. But it helps tremendously for that code to be prefaced by information that helps orient users.

Your README can be flashy or slick, and there are many great ways to give it flair. Including screenshots or GIFs of your app, adding links to video demos, using a linked table of contents, or implementing design features that make it aesthetically pleasing, are all bonuses.

But ultimately, a well-crafted README can be relatively simple. At minimum, it should include the project’s title, some context for the project’s development, and user instructions.

For further reading on this topic, especially in the context of open-source repos, I recommend checking out GitHub’s own documentation on READMEs, or Akash Nimare’s post on READMEs, including his curated list of exemplary ones.

Committing to consistent commits

While READMEs can be composed at any stage of a project’s development, Git commits are made serially, throughout the life of the project. They document the context of each set of changes made, so it pays to spend an extra few seconds making sure each commit message is expressive and well-formatted.

At minimum, good commit messages should clearly communicate the context for the changes being committed. They should be kept concise and descriptive; it’s generally agreed that commit message subject lines should be limited to no more than 50 characters, with a hard limit of 72 characters. Where necessary, include a longer description following the subject line.

A good rule of thumb is to commit each time a single unit of change is made, meaning that in the majority of cases, one-line commit messages should be sufficient to describe changes.

In the following command-line syntax, the “-m” allows for the user to include a commit-message subject line inside quotation marks:

git commit -m "Refactor PetsController actions"

If your message won’t fit on a single line, the “-m” syntax is less ideal; you can configure Git to generate a custom commit message template that incorporates both a subject line and a body.

Commit messages should adhere to a consistent style and formatting. If multiple developers will be collaborating on a project, they should agree on their approach to that style and formatting from the get-go, if possible. The accepted convention is to conjugate commit message verbs in the imperative mood (e.g., “write,” “change,” “run”, “install”). This can feel a bit unnatural, but imagine you are telling your code what to do with the change you just implemented.

git commit -m "Add destroy action in PetsController"
git commit -m "Fix bug in pets show page nav bar"

Remember, it would be redundant to include timestamps or any of the specific lines of code that you changed, in your commit message — this information is automatically tracked by Git and accessible in your diff when a commit is made.

For a deeper dive on commit messages, I highly recommend Chris Beams’ excellent best practices article.

Final Thoughts

The best developers give thought not just to the code that they write, but to the presentation of that code and its accessibility to others. Investing just a bit of time in crafting informative READMEs and commit messages are two simple ways to make your code sustainable and user-friendly.