RFD 3

Writing Programs

Elias Groot Elias Groot

A small collection of important thoughts on writing software.

Programs must be written for people to read,
and only incidentally for machines to execute.

— Gerald Jay Sussman

We believe that to be a good developer, you must be able to understand and reason about both the technical details as well as the user needs. To be a great developer, though, you need to understand that the quality of any of your work is determined by the reader, never the writer.

Unfortunately, this is something that everyone has to experience at some point. You can write the most compact code, if your colleague does not understand it, it is not useful code. Similarly, if an end user does not understand the sign up workflow you worked on, they are (most likely) not using it wrong.

As frustrating as discussions with readers can be, they can be easily prevented by following common guidelines that we have collected or created over the years. Some of which are inspired by John Ousterhout's "A Philosophy of Software Design".

Reduce Cognitive Load

Increased cognitive load is the number one symptom of sub-optimally designed programs. It appears in many forms, is hard to eliminate and easy to introduce. It creeps into a codebase as a slow but steady productivity killer.

Fighting cognitive load is a long-term investment, where benefits are aligned with those of developers, clients and end-users. While sometimes abstract, there are concrete guidelines to prevent cognitive load from entering our codebases.

  1. Define once. As soon as there is more than one source of truth, you introduce cognitive load.

  2. Eliminate unknown unknowns. Effects of changes should be enforced by a compiler, not by conventions. Unknowns should be explicitly incorporated into the codebase, and as a last resort, documented close to the source.

  3. Reason locally and rely on types. External assumptions can safely be encoded into a type system and invariants can be enforced by validators and compilers.

  4. Describe the why, not the how. The how is explained deterministically in code that is uninteresting. The powerful part is the why, which is captured in comments and wikis.

  5. Acknowledge that programming requires empathy. When making a contribution, try to place yourself in the head of your colleagues. Even thinking about coming back to this code in a few months yourself will most likely make you a better programmer.

...this RFD is still being drafted