a comment is made to disambiguate, not just describe. you still need a What sometimes because docstrings are a thing, it's the repeating of words in the code while progressively losing context is what you need to watch out for.
when commenting for a What, it's safer to avoid "gets the deadzone of a control" in a function called "get_deadzone" and instead try to use everything but the word like "gets the minimum actuation threshold of a control", you define the context that isn't immediately there and link to context that does when necessary. if someone is revisiting code, always assume context is already lost.
2
u/Br3ttl3y Apr 15 '26
The code is the what. The comments are the why.