Re: [Chicken-users] Re: dbus:send bug

[Peter Bex]

On Wed, Mar 16, 2011 at 02:58:59PM -0300, Stephen Eilert wrote:
> > Documentation for eggs is usually manually written.  As far as I know,
> > nobody uses automatic extraction of comments from code.
> 
> And that's a shame.

Why?

Almost all the "extracted" documentation I've seen is of shitty quality;
people tend to use automatic extraction of docs as an excuse not to
write proper documentation.

Also, writing documentation by hand forces one to think about writing
it in a way that it can be read from beginning to end and have it make
sense.

Having documentation on a wiki means people can add notes about and
rewrite sections they found difficult or hard to understand, thereby
increasing overall quality.

Finally, when the inline documentation *is* done really well, you end
up with a lot of documentation getting in the way when you're trying to
read the code.

Cheers,
Peter
-- 
http://sjamaan.ath.cx
--
"The process of preparing programs for a digital computer
 is especially attractive, not only because it can be economically
 and scientifically rewarding, but also because it can be an aesthetic
 experience much like composing poetry or music."
                                                        -- Donald Knuth