* functional style makes it easier to split stuff since you mostly transform immutable data
In the Article IO, State (side-effects) and Data transformation is mixed in both versions. That leads to unnecessary complexity. In that case worse if it hides in sub-functions. But separate it and the right version is better. (you can answer the question about idempotency easily now)
* Comments over blocks of code are harder to keep in sync with the code below, they require more discipline from all team members
So in theory they are nice, but you will never have them unless you enforce them through proper code reviews.
I agree with the Functional style part, but hardly disagree with your second point.
Because of the fact that, keeping comments over blocks of code in sync with the code below requires the same exact amount of effort (arguably less) as keeping function names (and ideally, documentation) in sync with the code inside..
Except that, if the second one is not done, that is a lot more dangerous than the first- exactly because, every time you define a function, you are declaring an abstraction, and if the abstraction changes silently, that's where the real mess begins.
That's what ends up happening in my experience. (See also sibling other comments about the proliferation of flags in a function signature)
(Needless to say, I strongly resonated with the OP as I also love linear code with comments, but in the end it's also a matter of taste..)
* functional style makes it easier to split stuff since you mostly transform immutable data
In the Article IO, State (side-effects) and Data transformation is mixed in both versions. That leads to unnecessary complexity. In that case worse if it hides in sub-functions. But separate it and the right version is better. (you can answer the question about idempotency easily now)
* Comments over blocks of code are harder to keep in sync with the code below, they require more discipline from all team members
So in theory they are nice, but you will never have them unless you enforce them through proper code reviews.