>> A comment is just a summary of the code in an abstraction that's easier to follow.
I disagree. The code already tells you what it does. A summary has low value.
Comments should be for explaining the why: the reason the function uses a particular algorithm even if it's a bit slower, or why the return format is an unconventional shape or contains redundant bits. This is so that someone coming in later (either a human or agent) doesn't get confused or think that the function needs refactoring.
Summary comments have ended up as the bane of my existence everywhere I've worked, for one simple reason: they go stale and there's no way to prevent it from happening.
I disagree. The code already tells you what it does. A summary has low value.
Comments should be for explaining the why: the reason the function uses a particular algorithm even if it's a bit slower, or why the return format is an unconventional shape or contains redundant bits. This is so that someone coming in later (either a human or agent) doesn't get confused or think that the function needs refactoring.
Summary comments have ended up as the bane of my existence everywhere I've worked, for one simple reason: they go stale and there's no way to prevent it from happening.