Habitable Software

It seems like every few months I read some new way of articulating the idea that code that's hard to maintain and modify is frustrating. Some, like this, don't really pose solutions, some do, but most I think fail to realize that their advice inevitably falls apart in some case

Extremely modular/functional code can require understanding more separated moving pieces, which may well be scattered to the winds in a zillion different files and combined in clever but counterintuitive ways

Extremely object-oriented code has lots of mutability, inheritance, and encapsulation gotchas that make users of an API less likely to understand what's happening under the hood of some class

Extremely terse code can be difficult to parse the logic out of, extremely verbose code can take forever to read and be hard to hold in your head, extremely abstract code can be hard to parse out how it accomplishes the application, extremely purpose-specific code can be ridiculously idiosyncratic and be hard to separate into digestible pieces, and so on and so forth. I've heard a lot of code organization advice and could keep doing this for hours.

I had a student tell me a personal project's codebase looked like the necronomicon once after an overhaul I made to make it more readable from my perspective

There are sometimes takeaways from all these analogies and policies and just generally opinions about how to write code people can supposedly maintain or modify or read more easily, and I definitely use and take some of them to heart. But most advice is really bad at generalizing, and I often feel that the most readable style of code is whatever one that I prefer and can convince people who work with me on it to prefer (Or, you know, vice versa as the case may be)

The original: https://www.dreamsongs.com/Files/PatternsOfSoftware.pdf

The building analogy doesn't work, software is not a building. There are essentially templates for buildings, there is no template for software.

Maybe software is more like a city. Maybe buildings are more like patterns, data structures, etc.

I’m not entirely sure I would want software to be « engineered » like old farmhouses. They were not modular by design but often hacked to be tailored to the usage. It is not that different from hackable software. You can change part of it but everything is not possible. And it creates stability and reliability issues. I prefer engineered software like the superdome. You know what it is for, you can optimise it for its usage. And what is great with software is that when you don’t need it anymore, it doesn’t bother anyone. Unlike olympic games installations for example…

The number one characteristic of uninhabitable software as above defined, in my experience would be the inability of people touching it to look past today, and past themselves.

There is a degree of hack that should be unacceptable. If you're using what's at hand and not what's preferable, you should stop to think. If you're rushing to meet a deadline, open a new branch marked "hacked-to-deadline". If you're using something you're proficient with instead of learning what is commonly used in such a situation, you're not a hacker, but a worker.

A hacker is an aspiration, and a noble discipline. Meaning you are not to decide if you're a hacker, but the people you respect as such should decide for you.

And discipline is key word in there. A discipline is both a pursuit and a technique. Seeking and sadhana. Feeling AND understanding.

There is no place for workers in an open-source project. There is place for goals, instrumental goals, hackers and automation. Explain what you're doing, have clarity. Clarity leads to less features, more usefulness, better documentation that isn't confused wrt/ what the code is actually doing.

Work it out in a draft branch, scrap it and code it again the way it is required to be to remain clear, driven by one clear approach to a goal that is well defined. If you leave a placeholder, clearly mark it as such in place, and in the backlog as a FIXME.

Do what you'd want others working on the thing to be doing, leave time to hack on what titillates your inner joy, as well. Eat the frog, but have cake ready.

This kind of discipline is demanding. If it's sounds too demanding then your perception has not graduated to hacker levels. Hackers love complexity. It is a thing to neatly pack into your requirement space, a cute puzzle, and a lovely time.

Hackers love constraints. Those are the bedrock on which we build continental machines of universal magnitudes of influence.

Hackers love requirements. Once the problem space is well defined, and goals are clearly approachable, those are the things that drop, one after the other falling off the wagon. Hackers love to get rid of ill-conceived requirements.

But that last part you have to graduate to, with discipline. If you think you're there, you should be able to think outside yourself, defend your discipline and it's application in your code. And others will decide if you're making sense or not. You can not be it.

I'm not sure any specific pattern or structure could possibly be good for all software.