Sometimes comments like that are good- I totally support adding comments in code ex. to document what algorithm you are using.

Also, (quote not from public channels, but idc)


Assembly code, when heavily optimized, is virtually unreadable to mortals.

Since the "no comments except api docs" rule works because your code should be clean and readable even without comments, when your code is optimized to the point of obfuscation you should comment your code (as the rule no longer holds).

Honestly assembly is not that hard to read if you don't have comments. Add an API to what certain calls do, and it's perfectly understandable. Adding more comments is just confusing.

The more complex your program, and the more components it contains, the less likely it is that you will be able to remember how it works. Add good comments (without simply explaining lines, see existing tips), but also keep whatever external documentation, text, and diagrams is necessary to explain your code.

This goes 10x-100x if there's anyone other than you who will or might work on the project in the future. My viewpoint has gotten a little skewed now that I work on enterprise-scale code with many simultaneous authors most of the time, but it's still good to get into this practice with smaller-scale codebases. And if you can, get into the habit of using version control properly, including good-sized commits, feature branches, tagged releases, and PRs.