Subject: Re: ZAP/[patch] Martin's cursor position POW
From: Dom Lachowicz (cinamod@hotmail.com)
Date: Thu Jan 25 2001 - 01:18:00 CST
Sam TH wrote:
>2) Comments.
>
>This is something new that I want to suggest. I think every new
>function that we write (at a minimum, all the XP ones) should have at
>least a short comment, preferably for Doxygen, explaining what it
>does. If we follow this practice, our code will soon become much
>clearer and easier to understand (keep your fingers crossed).
>
>What do people think about that?
I really like the idea of inline self-documenting comments (I'm a Java-head
at work, so things like JavaDoc end up saving me lots of time and just come
naturally). I suggest that *all* new exported functions get commented in the
C++ file, whether they are XP or "P". Tricky non-exported (static) functions
should probably also get commented. It really does help cut down on overhead
and leads to a clearer view of what's going on.
Our business calls it "due practice" - i.e. our customers asks for not only
the product but also our documentation of the code and system. They
generally send this off to outside firms to have them audited so that they
are sure that our stuff is up to spec and reasonably maintainable. I see no
reason why AbiWord should not adhere to similar criteria.
Dom
_________________________________________________________________
Get your FREE download of MSN Explorer at http://explorer.msn.com
This archive was generated by hypermail 2b25 : Thu Jan 25 2001 - 01:18:04 CST