Reading

Carl Kolon

/ Reading

@carlkolon

Carl’s Required Reading

As an engineering leader, I often send articles to my team, which I jokingly call “required reading”. My goal is to help us digest some of the wisdom of other programmers who have probably faced challenges similar to ours. By popular demand, I’m putting the list here for anyone else interested!

Most articles are on this list because they make a point that I think is important or insightful about how to create good software. Some of the points in here reinforce my opinions about certain things (for example, ORMs are bad, and frontends should be simple). You may disagree! But at least you will hopefully get something valuable out of the article, even if it is that you feel the opposite way.

These articles are technical, and if you are not a programmer you will probably not find them interesting.

This list may be a little overwhelming, so I have annotated my favorite articles with a star. I have also written a brief summary of why I think each article is important.

Coding practices

⭐ The Grug Brained Developer

If I could recommend only one article to new and experienced programmers alike, this would be it. Complexity bad.

The Wrong Abstraction

It’s really tempting to see code duplication and immediately rush to eliminate it by consolidating it somewhere. This essay is adapted from a 2014 talk about factoring object-oriented code and talks about situations where this may not be appropriate. You need to understand this to effectively push back against coding agents which are motivated to create a “single source of truth” everywhere.

Complexity Budget

When projects get too complex, progress seems to stop very suddenly. This essay is about understanding this phenomenon and trying to forestall it as long as possible.

Locality of Behavior

Programmers (and coding agents) often try to achieve Separation of Concerns (SoC) or eliminate code reuse by creating numerous helper functions. There’s a tradeoff between this and Locality of Behavior, a principle which encourages us to make the behavior of code as obvious as possible when looking only at that one unit.

Yagni

Creating speculative features with the future in mind is basically always a bad idea.

Parse, Don’t Validate

This one takes a little work to understand, but the basic idea is that if you ensure that a piece of data has a certain property, you should encode that property directly in the object’s type. This will cause code changes that break the assertion to throw type errors at compile time, rather than value errors at runtime.

Platform

⭐ Steve Yegge’s Google Platforms Rant

There is a ton of really good stuff in here, especially about accessibility and setting up software organizations. I do not recommend every company enforce the Bezos mandate, but you should think critically about whether you can expose your service’s features to other teams in a programmatic way. It’s also just fun to read.

Frontend

⭐ HATEOAS

In web applications, state is often encoded and stored separately from both the frontend markup and the backend (for example, with React’s useState). Often, it makes more sense for state and the user’s allowed actions to be directly stored in and derived from the html served to the user. This is tightly related to the original concept of a REST API (most modern “REST” APIs do not actually follow the REST constraints). I have also written briefly about HATEOAS on my own site.

Components and Hooks must be pure

The biggest problem I see when people move from writing backend code to writing React is that they try to write the frontend imperatively. That is, they try to tell the computer what to do, line by line. This typically involves the overuse of state and side effects, common in object-oriented programming. Instead, the frontend should be declarative. That is, you should tell the computer what you want to get back. To support this, (modern) React is designed around a functional programming style. Every component is a function, and state and side effects are avoided except for where they are truly necessary, in which case hooks are required. I recommend reading all the React docs, but if you just want to focus on one, this is the best.

Understanding useMemo and useCallback

useMemo and useCallback are the most misused hooks in React (besides maybe useEffect), and both agents and humans love to throw them in everywhere. This article is a guide to where they are actually necessary.

Hypermedia Systems - Components of a Hypermedia System

If you want to write a good frontend, it is very valuable to understand the model around which HTML is based. This is a great chapter of a great book which will help you maximize your use of the browser’s design, rather than seeing HTML as “an awkward, legacy markup language that must be grudgingly used to build user interfaces in what are increasingly entirely JavaScript-based web applications.”

Databases

⭐ The Vietnam of...