On Thu, 11 May 2000, Jamie Lokier wrote:
> Roman V. Shaposhnick wrote:
> > > May I humbly suggest you name the argument `struct file * file_or_null',
> > > so that filesystem implementors don't make the mistake of assuming it
> > > is always set?
> >
> > Hm, I guess that what we need is somekind of documentation on this topic,
> > just to prevent further discussion of what adress_space_operations should be.
> > I bet that after a while there will be a lot of people asking just the
> > same questions and suggesting just the same that will "make things more
> > general".
>
> <rant (for no particularly good reason)>
>
> Do bear in mind that documentation drifts out of date quite easily; when
> it is there, it isn't always easy to find, and many people code based on
> other examples of code instead of looking at the documentation.
If it doesn't seem inherently obvious that the parameter could be NULL (and
I'm not disputing that), why not describe it in a COMMENT where usage _and_
nuances could be discussed? Unlike separate document, a comment with the
function header shouldn't drift if the code changes. (Okay, neither should
a separate document, in an ideal world.)
Changing the parameter name to "file_or_null" to make it self-documenting
seems very awkward, when a simple comment could do a better job of making
the code self-documenting. Anyone who "uses the source" (Luke!) would see
the comment and understand that the parameter could be NULL. Better yet,
the comment might explain when and why a NULL would be sensible, making for
better understanding of the code.
Isn't this the obvious solution?
Deven
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.rutgers.edu
Please read the FAQ at http://www.tux.org/lkml/
This archive was generated by hypermail 2b29 : Mon May 15 2000 - 21:00:18 EST