Subject: Re: Documenting the AbiWord Program
From: Jesper Skov (jskov@redhat.com)
Date: Fri Dec 22 2000 - 15:35:28 CST
>>>>> "Randy" == Randy Kramer <rhkramer@fast.net> writes:
Randy> * Add comments aimed at several different levels of reader /
Randy> programmer.
This is difficult to achieve since all the comments should appear in
the code "in situ".
Hm... Maybe use a special syntax for very verbose comments, a la:
/*V ... */
And people who don't want to look at very verbose comments can use
syntax highlighting to tone down anything matching that pattern.
Randy> * Do the commenting in such a fashion that it can easily be
Randy> updated when the program is modified, and that, if it is not
Randy> updated, it is immediately obvious that the comments are out of
Randy> date.
I think most experienced programmers would agree that the most useful
form of documentation is a short primer to the function / construct
that describes input/output and how the magic works. Very low-level
details are best left documented in the form of code - after all,
expresing the program flow is best done with strict language semantics
rather than vague "human" explanations.
Of course, some functions use very powerful magic, and it may not be
immediately obvious even to an experienced programmer what's going
on. In that case a few helpful comments throughout the code comes in
handy (and assertions are even better - again avoiding confusion on
account of being strictly logical).
Randy> PS: I don't mean to imply that the AbiWord program is not
Randy> adequately documented. It may be very adequately documented
Randy> for a proficient C++ programmer. It is not adequate for me as
Randy> a newbie. (I downloaded some earlier version of the code,
Randy> perhaps 0.7.8, and tried to understand it. In the new year, I
Randy> intend to try again.)
It certainly isn't so well commented that some average hacker like
myself can start hacking without spending some serious (i.e., too
much) time reading the code.
I feel that we need more documentation of stuff "as seen from
20000-feet" - there are a few .abw documents and a single .html
document on some of the design issues, but it's painfully lacking for
thickheaded people like myself.
I have also considered suggesting adding DocBook function descriptions
in the same way as Alan Cox started doing it for the Linux kernel,
allowing us to generate a document with APIs and general descriptions
of the various components and how they interact.
I hope to get to spend some time after Xmas walking the walk instead
of just talking the talk, starting to understand and document the
fmt/ptbl backend code... But we'll see. I'll probably end up wasting
my time on other stuff...
Jesper
This archive was generated by hypermail 2b25 : Fri Dec 22 2000 - 15:35:33 CST