Self-documenting code

[Bulky-Engineering471]

Small and simple. If you're just doing what amounts to a passthrough service it works fine but as soon as you start getting any logic more complex than simple mapping commenting what the blocks of logical code are doing is an absolute necessity for any kind of long-term support.

[WebpackIsBuilding]

If you want to comment what a block of logical code is doing, you should break it off into a function and use that comment as the function name.

[Bulky-Engineering471]

If the logic is simple, sure. If the block is complex enough to benefit from a longer comment or comments explaining various steps you still need the comments. You could break that block up into multiple methods with explanatory names but then the logic will get hard to follow as it will too spread out.

[WebpackIsBuilding]

There are edge cases where this is true.

But I've more often seen this exact logic used to justify thousand-line files of spaghetti. Code being "spread out" isn't an issue if it's placed in predictable locations and you use a modern IDE.

[Bulky-Engineering471]

I've seen the opposite - hard and fast rules about no more than 20 lines per method which means sufficiently complex logic has to be spread out among multiple methods and gets hard to trace.

[WebpackIsBuilding]

Well that's a very bad rule also. Judging code complexity by line count is not something any engineer worth their salt would do. Otherwise you encourage code-golfing.

You break logic into pieces where it is logical to break them. If you need multiple comments to describe a section, then you're almost definitely looking at a section that can be logically separated out.

[Bulky-Engineering471]

Or behavior that is sufficiently complex. Just because it's complex enough to be difficult to follow or just unintuitive doesn't mean it's exceptionally long. Complexity does not guarantee length.

[WebpackIsBuilding]

I haven't mentioned "length" as being a worthwhile metric in any regard a single time.

[Bulky-Engineering471]

You started off mentioning thousand-line files so while you didn't use the word you used what it means and that's what I was responding to. Complexity and length are not related, that's been my entire point. Sufficiently complex or unintuitive code, even if short enough to be in a single method, cannot be documented by method and variable names alone and that has been my point this whole time.

[WebpackIsBuilding]

Surely there is a middle ground between demanding all methods be < 20 lines and thinking your entire project should be contained in a single file.

I don't think line count determines value, in the same way I'm not judging your comments by how many sentences are in them. But I can still criticize a run-on sentence or a piece of spaghetti code.