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--