[apothegm]

Comments should explain WHY. Why this needs to be done. Why we’re doing it this way instead of that way. Why this works when it looks like it shouldn’t. Why the business requires this rule/check/transformation/etc. why you would want to pass this param.

Comments that explain WHAT the code does are redundant if the code is reasonably self-documenting (as it should be).

Javadoc style docstrings should also be redundant, but sometimes it’s worth a comment to explain what a particular param actually does or is for, especially if it’s at all esoteric. `frobnicate_quux` is all well and good except I have no idea what a quux is or why I would want to frobnicate it when calling a function to send an email.

Unfortunately, there are a lot of tutorials in the training corpus, and tutorials are one of the few places where WHAT comments are important. LLMs have a bad habit of commenting like a tutorial.