Programs must be written for people to read, and only incidentally for machines to execute.
― Harold Abelson
More important to read a program than to run it? Absurd! How can something even be a called a program if it can't be executed by a machine? So soften the hyperbole: programs should first be written to be easy to read, and only afterwards optimized. It's the opposite of premature optimization.
The quote's hyperbole is good, because technical debt is caused by customers benefiting only directly from machines executing programs, as opposed to anything associated with people reading programs' source code. All maintenance programming starts with people reading. So this could be a programming principle that's more important than
extensibility, discoverability, clean code, clean architecture, SOLID, DRY, YAGNI, KISS, least astonishment, defensive programming, offensive programming, cohesion&coherence, consistent style, information hiding, and good separation of concerns. Let's call it the readability principle: programs should be written in such a way as to communicate their function as clearly as possible. "Function" refers to function which is meaningful to the user. "Communicate" refers to informing somebody who is not already familiar with the program, and not even an expert in all of the technologies employed. This implies that programmers should avoid both Rube Goldberg machines and fancy language features.
Knuth's literate programming is the original push to have a single program provide both function and documentation. Its most popular descendant is the Javadoc family, which is now the standard way to document APIs.
Jupyter Notebooks and
Devcards publish executable documentation.
Concordion brings together test code and documentation in a lovely way. All of these involve additional program documentation, which is not itself executable. Of course this should not distract from making properly self-documenting code. All additional documentation must have clear and agreed benefit, to justify the cost of manually keeping it up-to-date with the program itself.
The next big thing in program readability is humble: put design documents and technical specifications in the same repository as your program! And favor the markdown format. The best new source control repositories (Github, Bitbucket, and Gitlab) all render it automatically to the web. Having program and doc together makes it easier to keep them in the sync. Versions and links are easier, as well as running find-and-replace across program and doc. Perhaps most importantly, if you keep program and documentation together, you signal that programmers should maintain both.
