Subject: Re: commit - AbiWord Doxygen primer & style guide
From: Sam TH (sam@uchicago.edu)
Date: Thu Jan 25 2001 - 20:51:47 CST
On Thu, Jan 25, 2001 at 08:58:28PM -0500, John L. Clark wrote:
> 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.
I have to agree with John here. I think it's easier to learn the
structure of the code (or to find just the function you need) if the
comments are in the headers.
But more importantly, we should agree on one or the other.
What do other people think?
sam th
sam@uchicago.edu
http://www.abisource.com/~sam/
GnuPG Key:
http://www.abisource.com/~sam/key
This archive was generated by hypermail 2b25 : Thu Jan 25 2001 - 20:52:51 CST