How to code for humans

Good code is written for humans and executable by machines. This means that the human brain understanding your code is just as important – if not more so – as a machine understanding it. By understanding what the human brain is good at, and what it is not so good at, we can write code that functions better and is more easily maintainable.

With your code you are decribing functionality so precise it can be executed by machines. However those machines are not the ones tasked with fixing the bugs when they arise. The compiler doesn’t care if you call a variable e or fatalErrorCode. However, another human (or you in the future) might be tasked with fixing a breaking bug, at which point e might make it very difficult to figure out what is going on.

Code is read more often than it’s written and most developer time is spent chasing bugs. There is much to be gained from writing code that is easy to understand, both if you are familiar with the code or new to the team.

Here are some basic priciples that can help you write better code.

Human coding guidelines

Single Responsibility Principle

a computer programming principle that states that every module or class should have responsibility over a single part of the functionality – Wikipedia: Single responsibility principle

Tip: Describe every function, module or class in the – preferably inline – documentation. If the description of the function contains an “and” you know it does two things and needs to be split up.

Short term memory holds about 7 slots

An average human being can hold about 7 things in memory at a time. However, this is an average, so while some people might peak at 11, you might only be able to remember 4 that time you were hungover but had to fix a bug in production.

Don’t make me think

When reading code we need all of our brainpower to understand what it is doing, so write clearly and understandable.

Styleguides

Styleguides can make code more legable, help detect errors and make merge discussions a lot easier. Every team or project might decide on their own standards like PEP8, John Papa, BEM or StandardJS. Make sure the choice of style is well documented in the project’s README and preferably checked by a linter or auto formatted.


Inspiration and further reading

All Guides

Contributing

How to contribute to this City of Amsterdam Open Source project

Python backend projects

The style guide to the way we organize our Python back-end projects

How to code for humans

What we should think of when writing code so the most important computer we work with—the human brain—can parse it effectively

How we create cleaned, reproducable data for use in projects and apps

The way we make reusable data etl pipelines

How we create a docker environment for data analysis

How we set up a docker environment for analysis

How we code Python

The style guide to the way we code Python

How we track Open Source health

Understanding the impact and health of Open Source projects

How to write a README

The goto file to see what a project is and how to use it