[openbeos] Re: CVS IK Team Document
- From: "Erik Jakowatz" <erik@xxxxxxxxxxxxxx>
- To: openbeos@xxxxxxxxxxxxx
- Date: Sat, 10 Nov 2001 23:05:46 -0800
>I just did a fresh checkout of the CVS tree and saw the IK Team
>document go by. I took the time to read it and was impressed :) I think
Thank you. =)
>this is the perfect base for our developer guidelines document that the
>website has a spot reserved for. I'm personally in favor of this plan
>of attack, but feel a few things should be added before posting it to
>the web.
>
>First of all, the cool addon for BeIDE, for creating the headers should
>be approved of. With that I mean the content of the headers, the add-on
>is cool already :) I mention this because I mentioned tools like
>doxygen before, and I feel we should let the openBeBook be generated
>from both some seperate documentation, but also straight from the
>source. This makes it easy for developers to update the BeBook while
>making changes to the code, and if I remember correctly, an outdated
>BeBook was one the big problems with Be, Inc. (Also the fact that most
>technical writers there turned developer ofcourse :) ).
There's also a nifty addon for Eddie (which is my editor of choice)
called HeaderGuard which I've extended to provide a more complete header
heading ;P -- it could be extended further to provide function headings
as well (which I think is what you're really after here, yes?). My
personal feelings about doxygen style function headers are:
* I'd like them in the source files. I positively *hate* not being able
to take in a class at a glance because the header is clogged with an
tons of comments. Big comments at the *start* of the header are nice --
in fact, the perfect place for a general overview/summary of the class
and its usage -- but the heavy function headers should, IMO, go in the
source. It's just a hell of a lot easier to read that way.
* Aside from the summary comment at the beginning of the header,
doxygen-style comments should be pretty spare -- just the technical
details of the function (params, return, side effects, usage
constraints). Some of the function entries in the BeBook are fairly
hefty, and that seems like an awful lot to stuff in the source. Just a
preference; I can be swayed on this (heck, I may sway *myself* before
the debate is over ...).
>Please tell me what you all think about this and lets make this a top
>priority, before the CVS is full of different code and comments!
Yes, this certainly needs to be done -- count me in on the debate!
e
Data is not information, and information is not knowledge: knowledge is
not understanding, and understanding is not wisdom.
- Philip Adams
Other related posts:
