[gnaritas]

I abstract code with code, not with comments. Comments in general stink, and are used to express what code can't. If I can express it in code, it doesn't need a comment. Every comment is a sign that you failed to write expressive code.

If you need a comment to say what the next four lines do, you need a function for that, not a comment.

[flatline3]

Functions have maintenance and implementation overhead. They define an API that is accessible from the translation unit, and they thus require defining some amount of invariants. They also require breaking flow from the current function being implemented to hoist the code upwards.

A short, atomic unit of 4-6 lines of code does not deserve to be a function simply because it's an atomic unit, but it does warrant a simple comment that someone skimming the code can use as an index to determine where they want to look.

It's all about making the code approachable in bite size pieces for future maintainers, your collaborators, and your future self. Breaking it into pieces and describing the code means that maintainers are not required to trace out all the code and swap in a huge amount of knowledge just to determine what a given function does, and why, and what is safe to change within it.

[gnaritas]

> A short, atomic unit of 4-6 lines of code does not deserve to be a function simply because it's an atomic unit

And I couldn't disagree more with that statement, and virtually everything you've said. Maintainers don't need to look at a function to see what it does, that's what its name tells you and keeping functions focused on doing one atomic thing is what allows the name to replace the implementation and makes for well written programs. I despise programs written in the style you suggest.

A well written program is a thousand small functions/methods unburdened by long methods full of comments. Good code requires few comments other than those that explain implementation choices or class responsibilities. Comments are a code smell most of the time, they exist to make up for poorly written code.

[dllthomas]

I mostly agree, but "they exist to make up for poorly written code" should be "they exist to make up for less maintainable code." Less maintainable code may not be poorly written if other constraints (intense optimization in a critical path, for instance) force it on you.

[gnaritas]

Well, I did say to explain implementation choices which I think covers your point, as I do agree with you.

[dllthomas]

Yeah, I was just objecting to the implicit (and quite possibly unintended) value judgment.

[gnaritas]

Sure, I do like your phrasing better, less maintainable code.