Image for post
Image for post
Me talking about Line of sight in code at Golang UK Conference, London 2016

Code: Align the happy path to the left edge

Mat Ryer
Mat Ryer
Aug 25, 2016 · 4 min read

At the recent Golang UK Conference in London, I spoke about line of sight in code in my Idiomatic Go Tricks talk (slides are online) and I wanted to explain it a little further here.

Line of sight is “a straight line along which an observer has unobstructed vision”

Image for post
Image for post
Line of sight in code: Left edge is happy path, indented is error handling and edge cases

A good line of sight makes no difference to what your function does, but it does help other humans who might need to read your code. The idea is that another programmer (including your future self) can glance down a single column and understand the expected flow of the code. If they have to jump around parsing if conditions in their brains moving in and out of code blocks, it makes that task much more difficult.

Most people focus on the cost of writing code (ever heard “how long will this take to finish?”) But the far greater cost is in maintaining code — especially in successful projects. Making functions obvious, clear, simple and easy to understand is vital to this cause.

Tips for a good line of sight:

  • Align the happy path to the left; you should quickly be able to scan down one column to see the expected execution flow
  • Don’t hide happy path logic inside a nest of indented braces
  • Exit early from your function
  • Avoid else returns; consider flipping the if statement
  • Put the happy return statement as the very last line
  • Extract functions and methods to keep bodies small and readable
  • If you need big indented bodies, consider giving them their own function

Of course, there will be plenty of great reasons to break all of these rules — but adopting this style as a default, we have found that our code becomes much more readable.

Avoid else returns

A key to writing code with a good line of sight is to keep the else bodies small, or avoid them altogether if you can. Consider this code:

This represents how we might initially think about what our function is doing (“if something is OK, then do this, if there are no errors, then do this” etc.) but it becomes quite difficult to follow.

The ‘happy path’ (the route that execution will take if all goes well) is difficult to follow in the above code. It indents on the second line and continues from there. When we check the error return from something.Do(), we indent further. In fact, the happy return statement “return nil” is completely lost in the middle of the code.

It is very common for the else bodies to be a single returning line — in Go as well as other languages — as they deal with aborting or exiting the function. I don’t think they warrant indenting the rest of our code.

Flip the if statement

If we were to flip the if statements (! bang them, if you like), you can see that the code becomes much more readable:

In this code, we are exiting early and our exit code stands apart from our normal code. Also,

  • the happy path flows down the left hand edge,
  • we indent only to deal with errors and edge cases,
  • our happy return statement “return nil” is in the last line, and
  • we have fewer indented code blocks.

Promote big conditional blocks to their own functions

If you cannot avoid a chunky else body or bloated switch/select cases (I get it, sometimes you can’t), then consider breaking each body into its own function:

This is much easier to read than having lots of processing code inside the cases.

Share your experience

If you agree with me, please consider sharing this post — as the more people who sign-up to this, the better (and more consistent) Go code will become.

Do you have some code that’s tricky to read? Why not share it on Twitter @matryer and we can see if we can find a cleaner, simpler version.

Thanks to…

The reviewers Dave Cheney, David Hernández and William Kennedy.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store