Subject: Documenting the AbiWord Program
From: Randy Kramer (rhkramer@fast.net)
Date: Fri Dec 22 2000 - 11:07:05 CST
Hello,
I want to bring up a subject for discussion.
I've lurked on this list for quite a while, and have wanted to help with
the development of AbiWord.
In order to do so, I probably need to learn C++. ;-) (Also, because I
intend to program.) (You guys wouldn't consider translating AbiWord to
Pascal, PL1, or Visual Basic, would you?)
One of the common ways I've used to learn other languages (and programs)
is to take a program listing and start adding "penciled-in" newbie-level
comments.
If I undertake such an effort, I would like to make it useful to more
than just myself, possibly to the next newbie developer, or even the
next non-newbie developer.
I don't have a concrete approach in mind. I'm thinking along the lines
of a literate program. (I've written a Visual Basic program in Word
using a literate programming style.)
Some criteria I'd like to achieve:
* Add comments aimed at several different levels of reader / programmer.
* Let experts ignore newbie comments (they are either hidden,
unobtrusive, or removable). (In my literate Visual Basic program, long
comments were "unobtrusive" in the IDE because they did not wrap -- they
just extended far to the right (to infinity??) (and they were in the
comment color). In Word, the comments wrapped normally and were very
visible. All comments started with the comment delimiter, so I could
convert a Word document from word format to plain text (in the correct
flavor) and execute the program.)
* Do the commenting in such a fashion that it can easily be updated when
the program is modified, and that, if it is not updated, it is
immediately obvious that the comments are out of date.
* If the comments are removable, have a mechanism that allows them to be
reapplied to later versions of the program, and, like the previous
criterion, apply to the correct portions of the modified code or be
obvious that something has changed and the comments are out-of-date
(implies I might try to use CVS, diff, and patch).
If I start this effort, I suspect I won't finish it. I'll carry on
until I know enough about C++ and AbiWord to be able to meaningfully
contribute. (Unless this develops into the "perfect" way to document
the program.) I'd hope to leave something behind that is useful, and a
place to start for the next newbie developer who might take my work and
carry it a few steps further.
I'm not ready to start, but I would like comments about tools, methods,
approaches, or newsgroups to explore in preparation for starting such an
effort.
I'll listen but I don't expect to be swayed by recommendations that this
is not required. For me to get involved in the programming aspect, I
will do this, either "in-pencil" or in a more permanent form. If I put
the effort into it, I would hope to benefit more than just myself.
PS: I don't mean to imply that the AbiWord program is not adequately
documented. It may be very adequately documented for a proficient C++
programmer. It is not adequate for me as a newbie. (I downloaded some
earlier version of the code, perhaps 0.7.8, and tried to understand it.
In the new year, I intend to try again.)
Thanks!
Randy Kramer
This archive was generated by hypermail 2b25 : Fri Dec 22 2000 - 11:08:30 CST