Describing the what also helps when you dabble in a new technology or little-used technology. It helps to explain to yourself what you’re doing and it helps in onboarding. “Hey, newbie, there’s a function in XYZ module that’s extensively documented. Look there for guidance.”
Comments should explain “why”, the code already explains “what”.
The allowable exception is when the what is a what the fuck, as in you had to use a hack so horrible that it requires an apology comment
Or if the what is so cryptic and esoteric that it would require the reader a couple hours of research to understand it.
Also, I find it useful to summarise the what before code blocks if that can’t be summarised in a function name
Absolutely, although I see that as part of why
Why is there a horrible hack here? Because stupid reason…
Describing the what also helps when you dabble in a new technology or little-used technology. It helps to explain to yourself what you’re doing and it helps in onboarding. “Hey, newbie, there’s a function in XYZ module that’s extensively documented. Look there for guidance.”
Inline comments yes.
Function/Class/Module doc comments should absolutely explain “what”.
You are absolutely right. It was inline comments I had in mind.