Come 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.
If 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.
Knowing the assumptions gives the reader the context for why certain decisions were made, and why they may still be valid decisions or not.
reply