Software Development Guidelines

Drew Leske

Regardless of language or environment, there are core principles we follow in software development, to encourage readability, maintainability, and joy. Each member of the team is responsible for adhering to these principles and guidelines and to assist and encourage others in doing so.

More specific documentation describes our team practices for specific languages and environments:

Coding norms
…more to come…

Framing the guidelines

Follow these guidelines as best you can. If something doesn’t make sense to you, ask and clarify, and suggest improvements. Each of these guidelines is accompanied by its justification to help you understand why the guideline exists. If that justification doesn’t make sense to you, let’s hear about it.

These guidelines are not hard-and-fast rules. Adhere to them closely but if you need to deviate, then do so, so long as you know why (not least because you will probably have to explain it to the rest of the team during review).

For background and context for this document, please see this log entry.

Guidelines

Everything is to be in Git. Anything we produce must be in an appropriate repository, and for code and code-adjacent documentation, that’s Git.

If it’s only on your workstation, it doesn’t exist. It may as well be in your head since the rest of the team can’t get at it.
Commit changes regularly. Any significant change needs to be recorded, and better to err on the side of more commits than fewer. Significant here means anything you may want to revisit for any reason.

“Save early, save often.” It’s true for old-school adventure games and it’s truer for code. You record your progress so you can revisit earlier versions for reference or perhaps to return to previously working code. The log of commit messages can inform others of the code’s evolution and how and why it got to its current state.

If possible and feasible, delint the code and even unit-test it before committing. This reduces commits that consist of nothing other than lint fixes, and it can be helpful if code is in a known good state at any commit in some situations, like a complicated rebase. But this is secondary.
Use effective and descriptive commit messages. Follow the 50-72 rule and other well-established conventions for commit messages. This blog post describes the purpose of a commit message, and how to get there, very well. I also found this video helpful.

The point of a commit message is to communicate why a change was made. With a long list of commits it’s also important to be able scan them to find the change you’re looking for. Following these guidelines helps make the codebase much easier to navigate.

An effective commit message describes the change, and maybe why it was made. “Address review comments” is not helpful to a future reader; “Refactor sorting algorithm” is. In following the 50/72 rule, the extended part of the commit message is where you could put the “why”.
Use code comments and be more liberal than conservative: it is better to provide an unnecessary comment, such as describing what a variable is for when the variable name is perfectly adequate, than to not provide a comment necessary to understand the code. Extraneous comments can be caught and removed by the code review. (Of course, so will inadequate comments, but that slows down the review.)
All code is reviewed by at least one other person before being merged to the main branch or another principal branch.

It is important to understand what others’ code is doing, and it is important to get at least one other set of eyes on your code so your assumptions are challenged. Having a fresh perspective from somebody who hasn’t been in the thick of it can reboot your thinking.
Documentation is critical.
1. Every project has a README at its root, describing the purpose of the software, how to use it (essential and informative use cases, or if appropriate, just the usage text), and how to build a development environment in order to contribute.
2. Document enough that the rest of the team can quickly get up to speed on it, but don’t spin your wheels on it.
3. Don’t try to polish it every time, but try to improve every time.
Documentation is a first-class work product. Even if the application does not require user documentation, software is a living thing that needs maintenance, and effective maintenance requires documentation.

There are only two cases where software does not need documentation: a one-off script cobbled together to save time on a repetitive tedium, typically used only by the person who wrote it, and generally who’d be embarrassed to share it with a colleague; and software that is immediately going to be abandoned. But we don’t write software with the intention of abandoning it.
Knowledge sharing is important and knowledge and experience are to be celebrated.
- Every team member is to write a blog entry every month describing something they’ve learned. This can be technical or about the science at the heart of the project, or even about the team or collaboration. It does not need to be perfect and I’ll gladly help with editing, but it does need to be sincere.
- Regular meetings where team members describe what’s gone well for them and what hasn’t are critical for not only sharing knowledge but also for avoiding imposter syndrome and the like, and for increasing team cohesion.
Use standards where available.
- Use the accepted formatting standards of the language you’re using. This means, for example, four spaces for Python indentation and tabs for Golang.
- Use OpenAPI to define REST APIs, and if this can be used to generate code stubs then great.
Standards promote interoperability and portability–especially portability of your skills to other roles in your career.

Deviate only if and where it makes sense, and ensure the rest of the of team is in sync.
Use tools and environments used by those around you when appropriate.

Adoption by others should generally be an endorsement of its utility and quality, and means if you get stuck there is somebody around to bounce ideas off of.
If you use a tool longer than a day, whether you wrote it yourself or not, share it with the team. If we don’t have a place to share it, let’s find a place.

If you have a need and find a way to meet that need, there’s a good chance somebody else has a similar need and can benefit from your solution. Even if the need doesn’t quite match theirs or the solution doesn’t quite match their preferences, it may spark a more general or elegant solution. Even if it just gets a conversation started about workflow, sharing provided a benefit.
Mark off known technical debt in code with a flag. Use # TODO(dcl) There must be a more elegant way to do this or something similar (and appropriate to the language’s comment syntax). A CI job should then scan for these and tabulate them, creating a badge or some other visible reminder of the number of TODOs in the code.

It’s not always practical to find the ideal solution to a given problem on the way to meeting the greater need, so we leave a marker to come back when ready.

For example, we might leave a TODO if we aren’t sure that a particular algorithm will scale well under load, but we don’t yet anticipate that sort of load or quantity of data.
- TODOs should be consistently formatted and greppable: all caps, one word, and following conventions for the language, environment, etc.
- New members of the team, as part of their familiarization with the code, can tackle a number of these TODOs. This encourages getting into the code immediately without as much pressure.
All code must have test coverage. Automate this as much as possible–hopefully 100% because testing is boring. All code must be linted where possible to ensure compliance with formatting and other standards, as well as to find bad patterns and potential bugs.
Finally, in the absence of other guidance, follow conventions already present in the work.

Other guidelines

These seem less like principles and more like mechanics.

Don’t leave clutter in the code such as unused classes, variables, functions, or commented-out code. Remove unused files from the repository.

Code clutter is just added bulk and can slow and thereby inhibit understanding.

Chunks of commented-out code are just messy: if you’re going to comment out a block of code, consider adding a TODO so you come back to it; if there’s a reason to leave it in and commented out, place a meaningful comment at the top so we know why it’s there.
Start projects off from a project skeleton if one’s available.

Why reinvent the wheel? Especially when putting in all those spokes is so incredibly tedious.

We have one for Python projects for example; for other environments consider forking that for the new environment. Of course, they should be consistent so some common parts might need to be manually kept more or less in sync.
All source should be lintable for basic syntax and style, within reason. This often means putting a linter directive at the top of the file, as is the case for pylint, yamllint, and shellcheck.

This basic testing is cheap and easy and catches a lot of basic goofs.