[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: grace period [ was developers' guide]



On Wed, 2004-02-18 at 10:03, Nadim Shaikli wrote:

> This is the one item that doesn't gimme the warm-n-fuzzies.  I always
> comment my code enough for me to remember what the heck I was trying to
> do (and that is no easy task for my wrapped brain), yet I'm uneasy about
> having a "framework"/system in place that tells me how I should do it - I
> also know ZERO about doxygen (and thus the uneasiness), but we all learn

I think people are really overestimating how complicated this can be. It
could be as simple as:

/**
  * Use bits of the key to control branching
  * during a search
  *
  * @param link, Key, int
  */
Item searchP (link, Key, int);

That's all there is to it. Why is this such a big deal? You don't even
have to use keywords like @param and whatnot.

> and if its a must, I can certainly give it a try at a min to have a better
> stance in the future :-)  I think the intent here is to have the source
> code commented to some degree (in case people disappear and someone else
> needs to pick up), but I don't think doxygen will guarantee the quality
> of those comments.  I also think most (if not all) applications should have

No, only code audits will guarantee that -- which I hope we will
institute at some point. However, the Dev-Guide will guarantee that all
functions/methods will have 'comments'. 

> an accompanying 'man' (ie. manual) page (ie. application.1) geared towards
> the end-user and not the developer necessarily.

That is already covered in the dev-guide.

Regards
-- 
-------------------------------------------------------
| Mohammed Elzubeir    | Visit us at:                 |
|                      |  http://www.arabeyes.org/    |
| Arabeyes Project     | Homepage:                    |
| Unix the 'right' way |  http://elzubeir.fakkir.net/ |
-------------------------------------------------------

Attachment: signature.asc
Description: This is a digitally signed message part