grug wonder why big brain take hardest problem, factoring system correctly, and introduce network call too
seem very confusing to grug
^ This is the best and funniest paragraph of text that I’ve read this year
> given choice between complexity or one on one against t-rex, grug take t-rex: at least grug see t-rex
That section reminds me of The Litany Against Fear.
Edit "lets" -> "makes".
[1] https://en.wikipedia.org/wiki/Object%E2%80%93relational_impe...
Hate to "well ackchyually" the author here, but I'm gonna. The foundational data type in PostGIS is not geography, but geometry. geography is geodetic layer on top of geometry. I honestly don't use geography that much because it only supports a subset of the geometry functions.
http://steve-yegge.blogspot.com/2006/03/execution-in-kingdom... https://www.parsonsmatt.org/2017/10/11/type_safety_back_and_... https://lwn.net/Articles/336262/ https://tomasp.net/blog/2015/library-frameworks/ https://ratfactor.com/cards/not-quite-the-same https://matklad.github.io/2023/11/15/push-ifs-up-and-fors-do...
The last article links here, which I enjoyed:
https://venge.net/graydon/talks/VectorizedInterpretersTalk-2...
I think the lwn article on "the midlayer mistake" is somewhat the same point but to a different extreme, and in some ways libraries not frameworks too.
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.
If I could recommend only one article to new and experienced programmers alike, this would be it. Complexity bad.
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.
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.
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.
Creating speculative features with the future in mind is basically always a bad idea.
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.
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.
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.
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.
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.
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.”
I am a certified ORM-hater. I think they are seductive for new projects, but quickly begin to cause performance issues and confusion. As an example, see this OpenAI article about scaling Postgres:
Many of these problematic queries are generated by Object-Relational Mapping frameworks (ORMs), so it’s important to carefully review the SQL they produce and ensure it behaves as expected.
This is the best essay against ORMs that I have read and, even though it’s long, I recommend it highly.
Some more ammo in my anti-ORM crusade. This is more technical but more succinct, so if you’re just looking for the bullet points I’d read this.
PostGIS (and geospatial databases) require a little getting used to. It’s good to understand the new data types you’re working with when you build a map-based data visualizer. PostGIS is a great database and its foundational data type is geography1.
This is a great article to have read when your database starts slowing down. Knowing how to use EXPLAIN and EXPLAIN ANALYZE is on par with knowing how to use a debugger, in my opinion.
Most people use LIMIT and OFFSET when building pagination systems. If you are paginating through a lot of data, these get slow (especially when loading high-number pages). This is a good overview of some other options to get around this problem. I also talk about this on my site.
Many people are just thrust into async programming and don’t really understand what’s going on, but learn it as they go. Often this leads to embarrassingly basic asyncio mistakes like making blocking calls inside async functions. This is a good article from the docs which should make it clearer what asyncio is doing under the hood, and therefore teach you how to use it best.
Bob Nystrom is one of my favorite programming authors. This is an example of how async programming systems often have fundamental flaws. There’s not much you can do (besides use a different language) but this will at least teach you that some of the async programming limitations that you hit are fundamental, and not just a skill issue.
Reading this earlier in my career would have saved me hundreds of hours incorrectly parsing data collected from the internet.
These books have shaped the way that I feel about programming, design, and managing software projects.
Lots of people seem to think that “design” means making things look pretty. Really, design is about anticipating the needs of your user and making your product fulfill those needs as well as possible. Often this second meaning of design runs contrary to the first, and in these cases you should choose the second. The early example of “Norman Doors” in the book is a great illustration of this, along with the wry observation that the doors “probably won a design prize” even though the author can’t figure out how they work.
Liking this book is such a meme, but it actually is really great. It’s also one of the few programming books that works well via audiobook. My favorite chapters are 7 (Transactions) and 10 (Batch Processing). While some may disagree, I think this is a great introduction to databases too, and makes you think hard about what you actually want to optimize in your data system (even if you are not serving a zillion users).
This is a great, encouraging, fun book which teaches you how to build an interpreter, first in Java for simplicity and then in C for performance. While you can read along and write the Java code directly, I think it’s even better to try implementing the interpreter in another language of your choice, so you have to engage your brain more. I used rust.
While this book is a little hardcore, it’s the best intro to category theory that I’ve seen (though if you’re a fan of rigor, you may want to google some of the formal definitions yourself). Read this if you want to write good functional code while also flexing on your coworkers by using words like “functor” and “monad”.
This book was published in 1975 (!!) and revised most recently in 1995, but it is still incredibly relevant. In fact, as programmers become armed with AI tools, some of the chapters (like chapter 4, Aristocracy and Democracy in System Design) seem more applicable now than they were in 1995. Read this if you want to manage a programming project and have it succeed.
geometry, which you can read about here. It’s still good to learn about geography though, and the intro page is a little more accessible. ↩