Max wrote a couple of weeks back about how we do code reviews here. Writing high quality code is one of the most important things we do at MetaBroadcast, so much so that everyone has to code. For most of the team, coding is a central part of the role. For some it’s a past occupation—Mirona, Zach and I are all former developers. Everyone else gets the challenge of Code Academy.
Coding is an art, as well as a science. It takes a specific mindset to do well, and an even more specific mindset to do well while taking into account the requirements and views of others. Many of the most important lessons are softer skills, that apply way beyond code. For this reason, everyone joins our weekly code review.
It’s been almost 15 years since I had a job as a software engineer, I’ve never had a full time coding role at MetaBroadcast, and these days I spend almost zero time coding. For their own sanity, the team is keen it stays that way! Meanwhile, I’ve learned a lot by joining the code review sessions. I thought I’d share some of the main points. Each of them is quite obvious in software engineering, but sometimes it’s helpful to state the obvious stuff. More importantly, I believe they’re all applicable elsewhere.
get the names right, and the rest follows
As a developer, names are a huge area you have control of. Choose them well, keep them simple, make sure they don’t repeat the code (no defaultList or mainFunction).
This lesson was learned in product design a long time ago, and I believe it has legs well beyond. In one current project we spent a long time getting the data model right, and we’re insisting that the terms from the data model (e.g., Region, Authority) are used consistently across the full network of businesses that are involved. The names were chosen well to start with, and their consistent use then gives them great power.
good structure is clarity
As a developer, structure is also something you control. Get the structure right, and you get your thinking clear. Modern languages have many efficient ways to accomplish a specific task, yet often only one is truly intuitive.
Getting the structure right also allows you to put names in good places. If it’s not clear why you need this bit of the function, that’s probably a good sign that you need to split it into a separate function, and give it a name. This technique can be over-used of course, but there’s normally scope for more, not less.
This same process of declaring that a common pattern constitutes “a thing” (and also not doing it too much) is very valuable way outside software engineering. For example, here at MetaBroadcast we call a task that takes 2-5 man days of coding a feature, and we split as much work as possible into these chunks. We hang all kinds of stuff on this process, like daily updates, and ways to spot problems early.
reuse is clarity
We use Guava a lot. You might think you have a better way than a standard ConcurrentHashMap, and you might even be right (unlikely). Regardless, it’s a lot clearer if people come across a reference to a familiar component in your code, rather than your own home-rolled alternative, however great your alternative might be.
This same level of standardisation is useful way outside software. We have standard ways of picking up support issues, issuing invoices, and creating job offers. Sure, it’s quicker if you always do it the same way, but it’s also a lot clearer. Someone can be confident when working with our processes that the variation is in some specific areas (parameters, if you will), so the whole picture is a lot easier to understand.
brief comments are the sign of a healthy codebase
A few weeks back, a potential new team member completed the test that’s part of our recruiting process. He wrote a massive number of comments. Opinions varied, but we generally agreed there were too many comments for most people’s taste. Sometimes the need for many comments also pointed to poor code.
Our golden rule for comments is to say “why” you are doing something, not “what” you’re doing. This is possible because you’ve already written clear code, i.e., by following the rules above.
This is perhaps the best rule of all to take outside software development. If you’re already using good names, a clear structure, and reusing well know components, a long email about that new project becomes a single line statement that you’ll turn on a standard service for the customer.
I would be keen to hear the golden rules for good software elsewhere, and views on how these rules apply outside software. Contact us below, or on Twitter.