[jdev] Re: Re: The State of Our Code-bases

[Lucas Nussbaum]

On Thu, Sep 02, 2004 at 01:03:27AM -0500, Nolan Eakins <sneakin at semanticgap.com> wrote:
> Will Kamishlian wrote:
> > My inability to document the Jabberd 2 code base has been an continual
> > frustration for me.  When I started jabberdoc, I intended for it to be
> > half admin guide and half developer guide.  Thus, after the work I've put
> > in, I still see it as only half finished.
> 
> Do your docs describe Jabberd 2's database structure? I haven't entirely
> made head or tails of how all the tables work together just from looking at
> them.
> 
> > Documenting the code base for a one-person project is difficult.  I could
> > document the Jabberd 2 code base; however, I would need someone who could
> > walk the code with me (because I cannot read C). Given the scarcity of
> > resources on the project, anyone who could do that would need to devote
> > limited time that could otherwise be spent writing code or fixing bugs.
> 
> Learn to read C. Good code documents itself.

For a 10 lines advanced "hello world", maybe. For a 50000 lines project,
good code is often more difficult to understand than bad code, because
it is much more structured.

You just contradicted yourself : the jabberd2 dbs are only about 200
lines of good MySQL code, but you weren't able to understand them. Why ?
Because you were unable to grasp the 50000 other lines of jabberd2.
With good code documentation, you would have been able to focus on the
200 lines of mysql code.
-- 
| Lucas Nussbaum
| lucas at lucas-nussbaum.net    lnu at gnu.org    GPG: 1024D/023B3F4F |
| jabber: lucas at linux.ensimag.fr   http://www.lucas-nussbaum.net |
| fingerprint: 075D 010B 80C3 AC68 BD4F B328 DA19 6237 023B 3F4F |