> 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. Cons

> 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.)