When I started my current job, I'd put block comments everywhere in my code, saying what assumptions I was making and what was going on. Now, I've been moving away from gratuitous commenting: it's better, I think, to make the code speak for itself than it is to write bad code and tell the reader what it's supposed to do. (When that code changes, the comments usually get left out of date.)
My strategy now is this: write code to be as obvious as possible, and comment what's left over. Telling the user that &validate_foo validates a foo's value isn't especially useful, but saying that it expects a single reference to a foo is, for instance.
Update: Now that I think about it, &validate_foo is a horrible name for a subroutine, since it gives no clue as to what it returns. &is_valid_foo makes much more sense. (Although if having an invalid foo running loose in your code is a fatal error, then &validate_foo might just die or croak if the foo it was passed is invalid; if so, it should damn well be documented.)
--In reply to Re: Too much documentation?
by FoxtrotUniform
in thread Too much documentation?
by melguin
| For: | Use: | ||
| & | & | ||
| < | < | ||
| > | > | ||
| [ | [ | ||
| ] | ] |