How I Write Good Software

February 23, 2018

programming

5 min read

Your approach to building software is one of two things that defines how effective you are as a developer. The other is technology selection. Here is my approach:

Readability

My number one goal for all code I write is to make it as readable as possible. That is, if someone (for example, me a month from now, or someone who's never seen it before) looks at my code, how quickly can they understand what I'm trying to do? The sooner a developer can get their bearings in your code, the sooner they can contribute. I've had instances where I've spent hours poring through a piece of code before I understood it well enough to finally be confident in how to approach my problem. This time should be minimized.

This is, in my opinion, the number one goal of code. Everything else is in order to support enhancement of readability.

Keep it Simple

Simple code is easier to reason about than complex code. If I'm faced with a coding problem, I always think: "What's the simplest and most obvious way I can solve this?" A complex approach could run more efficiently or make you look smart, but it will most certainly increase the time it takes for another engineer to understand your code. We want to avoid that.

As Little Code as Possible

This is an application of the previous two ideas. As a rule of thumb, the less code there is, the less there is to reason about, the simpler your code will be, and the quicker developers will be able to understand your code. Don't do in 20 lines what you can do in 10.

Your Code is a Liability

Every line of code you write is a committment to maintain that code in the future. The less code you write, the lighter your maintenance workload will be. As a rule of thumb, I ask myself "Is this piece I need a differentiator in my project?" If not, I try to find a service or an external library to help. Which brings me to my next point:

Use npm Libraries

We know that less code is better, and the most effective way to use less code is to use someone else's! npm is the largest collection of open source packages in the development world, and it pays off in spades to use these packages and collaborate with the community. By using and contributing to open source packages we are sharing our most expensive resources: our developers.

Use Functional Programming Concepts

I've found that functional programming concepts have drastically improved the simplicity and readability of my code. It can be daunting to shift to fp, but incorporating one concept at a time makes it easier. React as a UI library can help since it promotes functional programming ideas such as immutability.

My favourite book for learning about functional programming is Kyle Simpson's Functional Light JS book.

Do Code Reviews

A code review is simply having a developer go and check over your code after you've completed it. I've found this useful even when working alone — I go back and check over my own code a few times to look for stuff that is unclear, incorrect, or unnecessary. Studies have shown that every hour of code review saves 33 hours of maintenance.

This is a massive savings that no development team can afford to pass up.

Do Test Driven Development

(when it makes sense)

When writing software that has a bit of complexity to it, it's useful to first write a requirement as a test, watch it fail, then write code to pass the test, and watch it pass. Then repeat for each requirement in that module.

I've also found simple post-deploy tests that check for a 200 OK response from your important URLs useful.

Writing Good Tests

A lot of teams nowadays aim for 100% coverage in their testing suites, which I disagree with. Sometimes the cost of writing a test isn't worth the value it provides, so it's worth doing a bit of a cost-benefit analysis before you try to test every single function in your codebase.

One rule of thumb I use is that if I can write a quick test to check the result of a single complex function, then I go ahead and do it. Another rule of thumb is writing a simple test for each bug I find so that it's caught if it happens again.

When to write tests is more of an art than a science, and I recommend exploring with more and more tests until you get a feel for what is worth testing.