One day you will inherit a code base so bad that you’ll end up commenting old code
Will not be the case, I won’t take a job, where I have this situation (or I’ll quit pretty quickly)…
Yeah my “comment standards” (btw. as others mentioned here, I was unprecise/unlucky with the choice of words, I meant “comment the why” or doc-comments totally fine and should be aimed)
Your so called comment standards and principals are fine if you are building something from the ground up
Yes that was also targeted with my comment. But what you’re referring to is just missing documentation, and I think this should be done on a higher level. The “comment why” rule applies for spaghetti code non-the-less…
Nah, it’s not, code is modular (IME should be kinda tree-structured), a book is linear.
So the API should be in your analogy the synopsis. And I haven’t said, that there shouldn’t be any comments. E.g. doc-comments above functions, explaining the use-cases and showing examples are good practice.
If your code needs comments, it’s either because it’s unnecessarily complex/convoluted, or because there’s more thought in it (e.g. complex mathematic operations, or edge-cases etc.). Comments just often don’t age well IME, and when people are “forced” to read the (hopefully readable) code, they will more likely understand what is really happening, and the relevant design decisions.