Shorter doesn't mean simpler (and other lessons about code complexity)
Tags: softwareengineering, codequality, productivity, bookreview
Published: 2019-07-07 09:37:41

---
title: Shorter doesn't mean simpler (and other lessons about code complexity)
published: true
description: A review of A Philosophy if Software Design by John Ousterhout
tags: software engineering, code quality, productivity, book review
cover_image: https://thepracticaldev.s3.amazonaws.com/i/0vad4pp88uwtgtequjrr.jpg
---

As software systems get bigger, they get more complex. Complex software is harder to improve. John Ousterhout, a professor at Stanford University, has recently published a really neat book that provides many tips for making life simpler: **A Philosophy if Software Design**.

The overall suggestion is that if your team is struggling with a spaghetti code base, its members should be investing about 10-20% of their total development time cleaning it up.  

The book's title is misleading. It mentions "philosophy", but the book i very practical in nature. It's small and short. Its messages are clear.  


## Why bother cleaning up the code?


If your team works smart, it's more likely to finish the project. Squishing each bug as fast as possible _feels_ faster, but you're likely to be adding technical debt over time.

![](https://thepracticaldev.s3.amazonaws.com/i/jkdj6aopvltqnjmavhtk.png)


## What can be done?

The book provides lots of advice, often drawing from experience reviewing code. Here are just a few tips that I've taken from the book.

- Focus on your interfaces and be deliberate about what you're abstracting. The sign of an effective interface is being simpler than the implementation. In a sense, the added complexity of a new interface needs to justify its existence.
- Rules such as "a function should be no more than _n_ lines long" is arbitrary an ineffective. Functions should be as long as they need to be to get their job done. Breaking functions into multiple sub-functions just adds complexity without benefit.
- Comments should document what the code can't. Comments that are purely pseudo-code are a distraction. 
- Design around the critical path. This is a really interesting one to me. It makes it much easier to think about where to start with the process of cleaning up a big code base, rather than worrying about the size of the whole task.

## Will it help me?

I'm a team member on a [code base with over 1 million lines of code](https://github.com/juju/juju). We've got levels upon levels of complexity built up over nearly a decade of development. Many attempts at reducing complexity have actually back-fired. They were never quite complete. That means that there are now two things to fix up, instead of one.

The book has given me a fresh perspective (& some hope!). It's also given me a new toolkit. I really appreciate the insight provided on almost every page. 

## Is it worth buying?

If your team is struggling under the weight of technical debt, then  definitely. If you're new to programming, probably. It's an accessible language-agnostic guide to becoming a better programmer. It's been a huge benefit to me.

----

Image credits: Cover image by [Rick Mason](https://unsplash.com/photos/2FaCKyEEtis)/Unsplash. Figure by Tim McNamara (@timClicks).