one level of abstraction per function (or paragraph)
Notes on functions from Clean Code:
- "The first rule of functions is that they should be small."
- "Functions should do one thing. They should do it well. They should do it only."
- "In order to make sure our functions are doing 'one thing,' we need to make sure that the statements within our function are all at the same level of abstraction."
- "We want the code to read like a top-down narrative. We want every function to be followed by those at the next level of abstraction so that we can read the program, descending one level of abstraction at a time as we read down the list of functions. I call this The Step-down Rule."
- "The ideal number of arguments for a function is zero (niladic). Next comes one (monadic), followed closely by two (dyadic)."
I'm taking all these points with a grain of salt, because I saw in a past job how a couple of them can lead us astray sometimes. But it's good food for thought.
how this applies to writing
These points have parallels in writing:
- Functions should be small — paragraphs should be small too (though they don't need to be tiny).
- Functions should do one thing — paragraphs should have one main point. Often, sections and articles should have one main point too.
- Statements within a function should be within one level of abstraction — Sentences within a paragraph should often be within one level of abstraction. Details past that should be relegated somewhere else (different section, footnotes, etc).
I remember thinking about levels of abstraction a lot when writing this investing guide. It comes up most in longer-form content.