[oneelectron]

Definitely agree on too-many-files. Documenting architecture is a whole 'nother art that's overlooked. We diverge on locating errant code though, big time.

You'd trip at my code in the payments example because whatever is 3000 for you would easily be 5000 for me. Not only do I write comments before each line of verbose syntax, but I also add blank lines after braces and between logical "blocks" of operations.

However, that structure also gives me a mostly searchable index of every logical block of my code. That gives me a very straightforward way to bisect down to the problem, no matter how far away that code is linearly. It feels like lots of little sandwiches instead of a giant sandwich, and I'm looking for one bad slice of meat. I at least can quickly scan and jump to sandwiches containing meat when they are so explicitly separated and annotated.

I'd also argue that since good comments (written before syntax) can be read as their own document, I also have full coverage documentation by default. If I wanted to produce a crazy deep documentation page, I could actually just pull every line starting with // or /* (but really I just use Docstrings/JSDoc/etc on top of my inline comments).

I believe I've arrived on this out of practicality. I maintain 10+ codebases of differing platforms at any one time, and my most frequent problem in life is arriving at a codebase and thinking "Okay, what was going on here?". My approach now is just "read the green" (I color my comments slightly green gray) and within minutes, I can understand the entire functionality of that code and search for patterns I know will exist. I don't believe that's possible in equivalent time by executing the program line by line in your head.