Subject: Re: commit - AbiWord Doxygen primer & style guide
From: John L. Clark (jlc6@po.cwru.edu)
Date: Thu Jan 25 2001 - 19:58:28 CST
Jesper wrote:
> People, please have a look at the stuff I've added. Would be nice if
> we could agree on a style (or on not having one) ASAP before we start
> getting a lot of comments written.
There's one point in your brief style guide that I would like to
generally discuss on the list. That would be point 4:
Put the descriptions by the function definition, not the
declaration (except inline accessors defined in the header
files).
My first inclination is to disagree, although there is likely some point
here that I'm missing. It seems to me that descriptions should be put
with the function definitions, in header files. The header file is by
definition supposed to contain interface information, both for the rest
of your code and the compiler, but also for the developer.
The first place I look for information about what functions I can call
(and therefore how a class should work) is in the header file. Also, our
implementation files are orders of magnitude larger than our interface
(header) files.
Instead of making the implementation files bigger, and
in the process forcing developers to sift through thousands of lines of
code for documentation on function x, I think we should balance out the
size between header and cpp files, and provide all interface information
up front. I know that's where I'd like it.
Take care,
John
This archive was generated by hypermail 2b25 : Thu Jan 25 2001 - 19:58:31 CST