> Remember that comments and documentation are no substitute for proper testing that will expose usage errors.
Which is pretty much what I was getting at. Consider the following pseudo-code:
Verify account takes an account ID, an optional enabled flag which, if
specified, will only search for accounts that have a matching enabled
status. The default is to search against all accounts. The return
value is true if the account is valid, false otherwise.:
account = new Account(id: 1)
assert account.search does_not_include id != 1
It is human readable and machine parseable. You get your documentation, usage examples, and tests all in a place that is far better suited for the job, in my present opinion. I welcome being swayed though.
(I'm not sure that code even matches what your comment describes, but I couldn't really figure out what the comment was supposed to really intend the code to do, which brings me all the way back to my original points. Sorry.)
Which is pretty much what I was getting at. Consider the following pseudo-code:
It is human readable and machine parseable. You get your documentation, usage examples, and tests all in a place that is far better suited for the job, in my present opinion. I welcome being swayed though.(I'm not sure that code even matches what your comment describes, but I couldn't really figure out what the comment was supposed to really intend the code to do, which brings me all the way back to my original points. Sorry.)