GnuCash developer documentation

Matthew Vanecek mevanecek@yahoo.com
23 Nov 2002 08:55:51 -0600


--=-zS5kJ3ZnsyTMGS/OK7CP
Content-Type: text/plain
Content-Transfer-Encoding: quoted-printable

On Sat, 2002-11-23 at 05:54, Christian Stimming wrote:
> Agreed too. If somebody asks, I'd vote for doxygen.
>=20

Doxygen looks good to me, and probably can generate a wider range of
output than javadoc.  I know there's other stuff out there, but if
everyone agrees, why don't we standardize on doxygen?  Silence is
concurrence...

> > > I really like Benoit's suggestion of moving documentation to
> > > header/source comments, because it's much more likely to be kept
> > > up-to-date there, than if it were a separately maintained entity.
> >
> > Source please, not header.  I know there are currently lots of comments
> > in header files, but I prefer comments closer to the actual code and I
> > think the are more likely to be updated there.  How much of your time do
> > you spend editing .c files vs. .h files?
>=20
> Header please, not source.
>=20
> Seriously, if my parts of the code are using functions from somewhere els=
e,=20
> then my code sees only the header files and so do I. The header file is t=
he=20
> place where the declaration takes place, and ideally the comment in front=
 of=20
> that declaration should give me absolutely enough knowledge to understand=
=20
> what that particular function is going to do. Contrary to that, a header =
file=20
> with undocumented declarations is pretty much useless for any human reade=
r.=20
> Note that we have two different questions here: On the one hand, the comm=
ents=20
> should be in a place where the user/reader easily finds them. Which would=
 be=20
> in the header. On the other hand, the comments should always be kept up t=
o=20
> date by the developer. Which does happen or not happen pretty much regard=
less=20
> of whether the comments are placed in the header or the source -- develop=
ers=20
> can forget it in both places, or can remember that in both places. Theref=
ore=20
> I would definitely vote for function documentation in the header.

Would it hurt to have it in both places?  That would be more to
maintain.  I tend to agree about having it in the header, unless the C
source doesn't have a matching header.  I really understand both
points--when you're working on a source file, it's more convenient to
have the comments there. OTOH, when you are coming into a system, you
tend to look at the headers.  There's probably not a perfect solution,
and it may depend on how well doxygen can weed out duplicate comments,
but I vote for putting official comments (i.e., API reference stuff) in
the header, and less formal comments in the source.  The API reference
is less likely to change on a day-to-day basis.

re coding style, how's this:

/**
 * Some constructive commentary
 * Beer is good...
 */
type *function(const char* arg)
{
    if () {
        something;
    } else {
        something else;
    }
=20=20=20=20
    for (x; y; z) {
        do {
            something;
        } while (stuff)
    }

    switch (var) {
        case Y:
            have a ball;
            break; /* a glass */
        default:
            get a ride;
    }
}

I like 4 spaces for indents (wish I was ambitious enough to make Vi
indent w/4 spaces instead of a tab...).  4 spaces creates enough
indentation to make reading easier.  OTOH (and this is a matter of
coding practice more than style), if you have too many nested
statements, the lower level nesting should be relegated to a new
function.  The less lines-per-function the better, IMO.  Keeping that in
mind, I like the above example.

I have seen flamefests about this type of thing before, and it's really
not as important as all that--it just helps make the code easier to read
when you have a standard and published style utilized across all the
code.

ciao,
--=20
Matthew Vanecek
perl -e 'print $i=3Dpack(c5,(41*2),sqrt(7056),(unpack(c,H)-2),oct(115),10);'
***************************************************************************=
*****
For 93 million miles, there is nothing between the sun and my shadow except=
 me.
I'm always getting in the way of something...

--=-zS5kJ3ZnsyTMGS/OK7CP
Content-Type: application/DEFANGED-35654; name="signature_asc.DEFANGED-35654"

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.6 (GNU/Linux)
Comment: For info see http://www.gnupg.org

iD8DBQA935b3OMmiB1jXEBsRAgNxAJoCSoFXYxNDtrSlOINeifPYEIq0EgCgoaUS
wqD34qq/cM1Q/UYT3N8zp/M=
=uZI0
-----END PGP SIGNATURE-----

--=-zS5kJ3ZnsyTMGS/OK7CP--