3 ms·
This strikes me as a good, but incomplete, taxonomy of comments. What about comments that describe our assumptions? I guess that's a special-case of 'what' com
by MaxBarraclough 7y ago
This strikes me as a good, but incomplete, taxonomy of comments.
What about comments that describe our assumptions? I guess that's a special-case of 'what' comments. Such comments are often better expressed as assertions in code (i.e. adding more code to improve readability, rather than reworking the code). Assertions have the considerable advantage that they don't go stale as the code is changed.
> although sometimes git blame will
That's a great point. Detailed commit messages are a good way to record the 'why' points. Unlike in-code comments, they don't bloat and dilute the source. Of course, they're also less immediate. (I guess I'm not sold on comment-folding as an answer to this.)
It's also a point in favour of fine-grain commits. If you squash your commits, 'git blame' becomes less able to help you track a line of code back to its original motivations.
- superhuzza 7y agoPersonally I would consider listing assumptions as a 'why' comment. Knowing the assumptions gives the reader the context for why certain decisions were made, and why they may still be valid decisions or not.
- MaxBarraclough 7y agoCome to think of it, 'assumptions' is awfully broad. I was thinking of in-code assumptions (We assume x is non-negative), but I think you're thinking of requirements-level assumptions? I agree that requirements-level assumptions (We assume the Vogon server will allow us to make at most 4 connections at any time) are exactly the sort of thing that should be captured in comments. I'm not sure there's a bright line between assumptions and requirements here, really. My other point there was that any non-trivial code-level assumption that can reasonably be captured with an assert, should be captured with an assert, in preference over a comment.
- mason55 7y agoIf you’re assuming x is non-negative I would want to know why. Is it a function of what x represents in the real world? Is it something that we agreed on but there’s no physical reason x can’t be negative? Did the dev just assume x can’t be negative because it was easy and no one ever talked about it? And if the code looks like it assume x will never be negative but there are no comments explaining why then I’ll assume it just wasn’t thought about/discussed at all and know to be careful around this code. That way when I go to update this code in the future I know if and why I have to worry about if x could be negative now.