CODE

Clear code begins with good choices at the most fundamental levels. When we think about "code as a system", we can begin to evaluate the inputs and outputs of that system.

Your code as a system

All code, whether written by one person or 1000 people, is a system. It has a series of inputs (code standards, literal keystrokes, documentation, langauge choices, and infinitely more) that generate a series of outputs (running software, broken builds, high incident response time, work on the weekends). Any decision made about code has a lagging indicator, as it takes time to see the effects of change. Because of that, we should try to limit the number of on-going changes that we have at any time.

How we think about code really differs depending on where the code comes from.

New Code

Existing Code

The Haunted Forest

The

Other People's Code

We don't always have control over what our fellow engineers write. We can leave reviews and guide discussions, but at the end of the day, working code is shipped code. When talking about and working with other people's code, we can find ourselves discussing hypotheticals.

"Why would anyone do this like this?"

"Who would build this in this way?"

"What kind of weirdo writes code like this?"

It's important to remember that historical value judgements are always a bad idea. A great mantra when dealing with this kind of code is: "Never attribute to ignorance what you can attribute to opportunity cost". We don't know the specifics of the situations in which this code was written. We don't know if a PM was pushing hard to get this done. We can't see all the other code they tried that didn't work.

If something is truly problematic, propose a change - more on this in the chapter on RFC's - but don't assume that your solution is right just because it is different.

Naming

Functions

Comments

Data Structures, Classes, Objects and Structs

Errors

Testing

Returns

Pick a paradigm

Don't Do Too Much

Write Everything Twice

In the world of programming, there may be no more widely recognizable than Don't Repeat Yourself (DRY). It's the subject of many a code review and you can find any number of articles explaining why DRY is the holy grail of programming. It's also wrong.

Alright, clickbait aside, let's dive into what DRY is, what good parts exist, and a better alternative.

Left high and DRY

DRY, in technical terms, is a system by which every "piece of knowledge" has a single, unambigous representation within a system.

In progress

Optimize for deletion

In progress

Perfect is the enemy of working

In progress

Deadlines wait for no dev

Never attribute to lack of thought that which you can attribute to opportunity cost.

Misc

In progress

Use a formatter. Use a linter.

Smells

In progress