Notes on "Notes to Myself on Software Engineering"

I just finished reading an excellent article about software development over on Medium by François Chollet entitled "Notes to Myself on Software Engineering."

The whole article is pretty good, but I wanted to point out a couple of highlights that, in my humble opinion, stand out from the rest.

In the section regarding APIs, under item number 4, Chollet writes:

"If the cognitive load of a workflow is sufficiently low, it should be possible for a user to go through it from memory (without looking up a tutorial or documentation) after having done it once or twice."

This is one of the most important points about API design that gets lost in the shuffle for an API to "do everything." A well-designed API is, on its face, simple. If you're looking to make a useful thing, you have to also make it easy to use. This is the kind of insight that a Lead should have cross-stitched and framed for their desk.

Item 4 under "On Development" also speaks to this point, generally:

It’s okay to say no — just because someone asks for a feature doesn’t mean you should do it. Every feature has a cost that goes beyond the initial implementation: maintenance cost, documentation cost, and cognitive cost for your users. Always ask: Should we really do this? Often, the answer is simply no.

Too often we find ourselves building one-off features that aren't really necessary in places where they don't really belong. These features increase the cognitive load on a user, mess up our well thought-out solutions, and dirty up our code. (They also have a weird tendency to do the exact same thing on the API side.) This is especially true for programmers like me who have spent large amounts of our career producing products for the specific internal use-cases of our individual companies.

I'd also like to draw attention to Item 3 under the same heading:

Taste applies to code, too. Taste is a constraint-satisfaction process regularized by a desire for simplicity. Keep a bias toward simplicity.

One of the things I use in code review to pick out pieces where a dev should have refactored is the length of a method. A method that runs for 1,000 lines is likely 900 lines too long, but a method that's 175 lines might be just fine. That "gut" sensation about something that is eventually going to cause a problem is an important part of the process, and I find the idea of identifying it as "taste" more pleasant than "code smell."

Taken together, I think these three items remind us to keep both the user and our future selves in mind when making decisions that effect the complexity and composition of our code and the systems it builds. They press towards simplicity and ease of use. And that is something very much worth keeping in mind as we go forward.

The rest of Chollet's article is full of other tidbits of wisdom that we, as devs, should keep in mind. And I encourage you to read the rest of it at Medium.