philm

Easy, it's just... continue programming in python. (large codebases are a mess in python...)

More seriously: Don't do that, it'll only create headaches for your fellow colleagues and will not really hit those (hard) that likely deserve this.

Almost... To be precise it's a Merkle DAG

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.

Don't get me wrong comments != documentation (e.g. doc-comments above function/method).

I probably was a bit unprecise, as others here summed up well, it's the why that should be commented.

Yeah that's a good summary

Yeah, but unironic...

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.

Good video I really recommend: https://www.youtube.com/watch?v=Bf7vDBBOBUA

SUUUUUUUUURE!!!11 I"M oN ITTTTTTTT

We're at 22.8̅2̅8̅7̅8̅4̅1̅1̅9̅1̅0̅6̅6̅9̅9̅7̅5̅1̅8̅6̅1̅0̅4̅2̅1̅8̅3̅6̅2̅2̅% slowly gaining rainbow ground

I just calculated exact subpixel accuracy, for me it's exactly 20.5̅9̅5̅5̅3̅3̅4̅9̅8̅7̅5̅9̅3̅0̅5̅2̅1̅0̅9̅1̅8̅1̅1̅4̅1̅4̅3̅9̅2̅0̅ % that is still missing to fill the whole comment body with rainbows, way to go!

Let's start the sixth rainbow!

Plenty of space for me still (browser version on desktop)