Managing your own mind

The most difficult thing in programming is to manage your own mind and to maintain an adequate mental “map” of the “territory” of the problem domain.

The phases of getting familiar and then attaining (gradually building up) of a thorough understanding of the domain are the most challenging, frustrating, painful and cannot be short-circuited.

The right understanding (to see the problem as it is) should come before the code (representations and concrete implementations).

Sketching and modeling (even before prototyping) with the rich Abstract and Algebraic Data Types is the best methodology a man ever invented.

All complex systems are hierarchical and layered, where, at least in principle, each layer interacts only with the layer right below it (not with any layer above or deep down) and asynchronous message-passing occur across abstraction boundaries.

The only solution I know is to disentangle and decompose the problem into a clear hierarchy of smallest, orthogonal building blocks or modules, while formally specifying (sets and logic) and writing everything down. Literally everything.

Every concept of the domain should, at least in therory, have a direct correspondence to a particular algebraic /type and therefore to a module which defines and implements it. The resulting dependency graph (an actual hierarchy) should be very flat (broad and shallow).

The utmost care should be taken to eliminate and prune unnecessary, redundant abstractions (which is the root of all evil).

Decent languages, like Standard ML, Ocaml or F# provide best in the whole world support for this kind of modularity (a hierarchy of small, orthogonal specialized modules, with application and specialization). Haskell, Scala 3, or Erlang lack the advanced features such as explicit interface definition, validation and application.

Ideally, it is just a deeply nested directory where each file (and filename) corresponds to a distinct concept of the problem domain.

The file-system hierarchy should roughly correspond to an abstract hierarchy of the problem domain inside your mind (and in your texts).

It allows your attention (and focus) easily zoom in and out through the mental hierarchy of the domain without getting distracted or messed up by irrelevant details and ideas.

In short, this is a technique to narrow and maintain ones focus and concentration, which are the most scarce and precious resources.

A project tree should have an obvious correspondence to a conceptual tree. John Carmack excels in doing this, and this is not a mere coincidence.