Be respectful, helpful and collaborative.

Writing software is hard. The problems we’re trying to solve are generally not trivial. They will have caveats and edge cases. They will rely on unreliable dependencies. The problem may evolve and the solution may need to be tweaked. The solution we’ve carefully crafted might not have taken into consideration something that later seems obvious. The problem might even change entirely.

How do we mitigate against these things, whilst allowing ourselves and others to come along later and build upon, change or fix our existing code? How do we as developers make working on future code enjoyable and productive?

At FreeAgent, the things we value in code mitigate against these things, and in doing so, we try to be polite and helpful to both our present and future colleagues.

Functionality

This might go without saying, but make sure your code works and meets the requirements you’ve been set. Think ahead about the problem at hand and don’t just dive in.

Verify that your solution is functional at each appropriate layer by writing tests. Write each test file with care by organising them in a way which is logical and hierarchical. Doing this will make it easier for others to find and verify that a particular piece of functionality is working as intended.

Design

The problem you’re trying to solve is often complex enough. Do your best to organise your code in a straightforward and pragmatic way which breaks down the problem, as much as is practicable, into manageable chunks. Do this by using the tools of your language or framework; good Ruby code, for example, will follow the principles of object-oriented design.

The less you and others have to think about how a bit of code fits together, and how it works, the more time you’ll both have to think about the problem itself.

Favour simplicity and clarity over clever coding techniques and conciseness. By favouring clarity, you’ll spot when things need to be broken out into separate classes or methods more quickly and won’t mask the complexity you’re adding.

If things are made simpler or significantly less verbose by adding complexity, make sure there is a good reason to do so and be pragmatic about your choices.

Others will be thankful that they’re not being bogged down trying to understand your code but are instead using their time to understand the underlying problem you’re both trying to solve.

You can always refactor later, but it’s much harder and less likely you’ll be able to simplify complexity.

The above guidance should naturally lead to a reasonable separation of concerns, however always keep thinking of how best to organise your code so that you’re not coupling together unrelated logic. You’ll be helping the next person who needs to switch out some underlying dependency and they’ll be grateful that they can reuse some of your code elsewhere, without having to rewrite or duplicate it.

When designing solutions, they should be relatively efficient and thoughtful of what is happening in operation and shouldn’t repeat work unnecessarily; on the other hand, always keep in mind that the slowest part of creating and running software generally isn’t expensive methods or CPU time, it’s the next human to come along and read your code.

Style

Be helpful to the next user by keeping your code easily readable. Do this by correctly and consistently aligning, capitalising and formatting your code and otherwise take pride in its appearance. Keep your code idiomatic to the language and project you’re working with so that other users keep their concentration on the issue at hand, rather than on the changing styles.

If you’re unsure of the standard to follow, try to have a look for a style guide — feel free to take a look at FreeAgent’s Ruby Style Guide if you’d like an example.

Name your variables, classes and methods in a straightforward way that is as simple and descriptive as possible. This will make it much easier to avoid code smells like unnecessary comments and will make your code less like code, and more like plain English.

Try to make your code pass the squint test. At a glance, can you spot if something is overly complex? It’s even better if you can try this out on a friend or colleague and get their opinion. If you find the code is too complex, try to investigate if there might be other ways to tackle the problem or if you could refactor your approach.

Maintainability

Write code that is straightforward, easy to follow, and easy to extend or modify as requirements expand or change. To do this, try to think about the hypothetical next step or change in requirements whilst designing and writing your code.

You should also keep your code maintainable by ensuring that your abstractions are appropriate, which will allow your code to be flexible enough for others to modify, whilst avoiding unnecessary complexity.

The above guidelines should help you avoid making assumptions that would require you or others to significantly rework or rewrite code, should requirements change.

Finally, allow others to collaborate on your code by writing maintainable, well thought out and readable tests. These tests will help the next user understand your code, serving as documentation, as well as giving them the confidence to alter and modify functionality, should it be needed, without fear of breaking any existing behaviour.

Writing software is hard, but we should all do our utmost to be respectful, helpful and collaborative with those who both read and build on the code we write, now and in the future.