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.