Actually, if we can get people behind doxygen, or some other technology, then
that'd be great, but I would say that any comments that had the needed information
would be just fine, regardless of the form.
On Instant Messenger, we are adopting something along these lines, prefixed before
each function written (JS or C++):
/*
* Name: foobar
*
* Arguments:
*
* int a; -- something about 'a' here
* int b; -- something about 'b' here
*
* Description:
*
* This function takes a, and b, and does some magic to come up with a value c,
which is
* returned to the caller.
*
* Return value: if a or b is -1, returns 17. Otherwise, 73 is returned.
*
* Original Code: [EMAIL PROTECTED] 6/25/2001
*
*/
If mozilla.org adopts something that allows the above basic content to be
expressed, we'll be all over it.
In addition to code documentation, we have, since 6.1 development began late last
year, made an effort to do design docs at the start of the project phase. We were
not terribly formal about how these docs were written, all we cared about, again,
was getting the info down somewhere (and putting it on the internal web site so
that people could reference it). This next time around, we will be firming up our
methods abit by using a more established method from industry. If it is successful,
I'll make a point of sharing what we have learned.
syd
Gervase Markham wrote:
> Syd Logan wrote:
> >
> > > Mozilla is an extremely large and complex application with a high barrier
> > > to entry for new engineers (particularly those outside Netscape.) Having
> > > each engineer spending a week doing a brain dump of stuff they know about
> > > their area would go a long way towards lowering that barrier, and
> > > increasing everyone's productivity.
> > >
> >
> > The importance of providing written designs and documentation early in the
> > process of development, is, in my opinion, very real.
> <snip good stuff>
>
> The reason I said we should document afterwards was because I was
> pessimistically assuming that people would want to code beforehand. But,
> as we approach the milestone, fewer and fewer people are going to be
> actively working on showstopper bugs. It's in this period that, in other
> milestones, people triage their bug lists and start on code for the next
> milestone, on branches or in local trees.
>
> Perhaps mozilla.org should try hard to persuade engineers to do
> documentation in this period before 1.0?
>
> > Or, consider you are a engineer who wants to contribute some software to
> > mozilla. Some components are rather well documented, others have
> > documentation that is old and invalid, and numerous others have yet to be
> > described.
>
> You are right, although I think everyone agrees that the level of our docs
> sucks :-|
>
> > I think a useful addition to the policies of mozilla.org would be the
> > insistence that a certain standard be met by contributors regarding how the
> > systems they are submitting to the source tree are described. If it is
> > important enough to be checked in, it is important enough to be be described
> > in such a way that maximizes its benefit to the community of developers who
> > must work with it.
>
> Hear, hear.
>
> > useable by anyone who cares to learn. I also call on mozilla.org to try and
> > derive some simple, effective, and, as much as possible non-intrusive means
> > by which this information can be gathered, and for mozilla.org to recognize
> > its importance and to enfore the policies that they put in place much the way
> > they enfore the requirement that code be reviewed and super-reviewed before
> > being checked in.
>
> Are we looking for something like:
>
> Every function should have a Javadoc/Doxygen comment at the head
> describing what it does, its inputs and outputs, and possibly what it
> _should_ do (the sort of comments normally buried in the source saying
> "XXX FIXME we need to handle condition Y".)
> Every module should have a manual for that module, which allows a person
> with no knowledge of that module to understand (at minimum) its general
> structure, relationship to other modules, high level control flow and so
> on.
>
> That would be a start.
>
> Gerv
