[ksri]

Great categorization!

Re. Guide comments - I usually try to make a smaller function with an appropriate name and then call the function. So long function become a series of invocations to smaller functions. This eliminates most guide comments IMO.

[karmakaze]

I came to make a similar observation re guide comments, with the difference that guide comments with inline code is better in most cases than a sequence of small function calls.

I've often wondered why my code style is moderate inline blocks with guide comments when I know about the benefits of good naming and self-documenting code. In the end, I find it more effective. By encoding in function names, you've (technically) eliminated comments but now buried what it actually does somewhere else meaning the reader must navigate to verify it does exacty and only what each reader infers from the name. I much prefer having a function of a small-medium logical size that I can hold in my head all at once and see relevant details without navigating away from where I'm reading/editing.

My experience is that less depth and fewer single-use functions aids overall comprehension similarly to how flattening as in list comprehensions or filter/map pipelines buys more headroom. I can imagine building/using DSL where everything is well-named and free of guide comments but I have never encountered such a thing where there are multiple committers using a procedural language.