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
