A Coding Maxim

Explicit organization of files into smaller chunks of code helps to ward off failures to create proper abstractions while also aiding reading comprehension.

Files are expected to grow with the functionality that they define, but one should avoid allowing files to grow with the implementation of the functionality that they define, as doing so tends to run counter to efforts of abstraction. Abstraction makes complexity manageable; it helps lower the number of balls one must simultaneously juggle.

Files should self-summarize behavior; literally concatenating more ideas together quickly overwhelms our modest faculties when it comes to reading comprehension — where does one idea end and another begin; where do I start reading and start skimming?. It is frankly much easier to keep a high level of precision among 20 files averaging 50 lines each than in one file with nearly 1,000 lines of code. There is more opportunity for self summary in the relationship between those 20 files, and it is quite likely that at least one or more of them will act as sign posts for anyone tasked with starting from scratch in understanding their behavior.

This maxim is really a paraphrasing of Edsger W. Dijkstra’s following reasoning about the imperative to pursue intellectually manageable programs. From The Humble Programmer (1972):

…the amount of intellectual effort needed to design a program depends on the program length. It has been suggested that there is some kind of law of nature telling us that the amount of intellectual effort needed grows with the square of program length. But, thank goodness, no one has been able to prove this law. And this is because it need not be true. We all know that the only mental tool by means of which a very finite piece of reasoning can cover a myriad cases is called “abstraction”; as a result the effective exploitation of his powers of abstraction must be regarded as one of the most vital activities of a competent programmer. In this connection it might be worth-while to point out that the purpose of abstracting is not to be vague, but to create a new semantic level in which one can be absolutely precise.



I fly planes → brooksmershon.com

Love podcasts or audiobooks? Learn on the go with our new app.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store