Source code should read like a newspaper

Do you remember the last time you saw great code? Code where it feels that you wrote it yourself, contrary to bad code you wrote earlier and forgot it was yours. Good code becomes great code when it is flexible and easily navigated through by the reader. When you stop writing code as soon as it does what it needs to, you forget the reader of the code in the future. You will do yourself a favor by refactoring the code to a readable and navigable form; organize it while the ideas are still fresh in your mind.

There are generic structures you can utilize for the source code you write. There is a sense of code style, just as there is a writing style in prose. This can be a technical code style, which is typically dealt with by a linter that enforces nitpicks. Yet, this is not the only style for your source code, there are also styles for ordering your code. An example is ordering your code by abstraction, which is commonly known as a writing style for newspapers.

In a newspaper, you typically read the headline first, and a first paragraph that describes the article; the abstract. Abstract here means the content described in the highest abstraction, which will be the main function of our source code by analogy. So should your main function contain all details directly? Not by this analogy, as a newspaper has further paragraphs to elaborate and discuss those details. Those details are not the concern of the abstract, that is implementation detail for the further paragraphs. Every paragraph adds more detail, and allows the reader to decide if they need to read on. It does not leave open ends because details sit in the way, as those lower level details are in the later paragraphs. Ideally, you can read any amount of paragraphs from the start, and understand the program. The further you decide to read, the more details you know; yet you are never clueless about the purpose of the program until you read everything.