Re: [Patch]: Little Cleanup

Michael Snyder
2007-03-06T20:40:08Z

On Tue, 2007-03-06 at 11:52 -0800, Joel Brobecker wrote:
> > > The place to document the meaning of a function's return value is at
> > > the function, not at each of its call sites.
> >
> > So you are saying that it's normal to expect the code reader to
> > constantly jump to the function's definition trying to understand what
> > its callers try to accomplish?
>
> Then perhaps this suggests that the function could be renamed into
> something clearer? But otherwise, yes, I agree with Jim and Mark,
> because maintaining these comments everywhere is going to be an issue.

Yes. The logical place for a function to be documented is
at the definition -- not at the call.