In trying to understand the new bio interface and other
kernel features, it dawns on me that I would be able to learn this
stuff faster and be less likely to make as many mistakes if the
declarations of function pointers and even external functions included
names for any parameters whose exact semantics was not absolutely
obvious. For example, one has to open another file when looking
at blkdev.h to figure out the meaning of:
extern int end_that_request_first(struct request *, int, int);
At least here, one can flip back to the source code for each
external routine in question (and there might be many), but, in the
case of function pointers, you can only look at how the function pointers
are used and the drivers that implement them, which is an easy way for
misunderstanding to arise. Just for illustration, here is one example
from fs.h:
struct address_space_operations {
...
int (*direct_IO)(int, struct inode *, struct kiobuf *, unsigned long, i\
nt);
};
I understand the dangers of verbosity, and I'm not advocating
naming every parameter or having length names. However, I do think that
naming parameters when the name can help clarify things will save
verbosity in the form of reduced documentation needs, save author
and reader time as a result of fewer questions, and may even improve
the quality of the software that people write to these interfaces.
Therefore, I humbly request the following small addition to
linux-2.5.1-pre7/Documentation/CodingStyle. I'm happy to submit
patches for specific problems along these lines that I find, but I'd
like to try to improve the situation at the source by adding this
three sentence paragraph of chapter 4 (Functions) of
Documentation/CodingStyle.
-- Adam J. Richter __ ______________ 4880 Stevens Creek Blvd, Suite 104 adam@yggdrasil.com \ / San Jose, California 95129-1034 +1 408 261-6630 | g g d r a s i l United States of America fax +1 408 261-6631 "Free Software For The Rest Of Us."
This archive was generated by hypermail 2b29 : Sat Dec 15 2001 - 21:00:14 EST