[jdev] Re: Re: The State of Our Code-bases
lucas at lucas-nussbaum.net
Thu Sep 2 02:03:17 CDT 2004
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
> > 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 |
More information about the JDev