[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Chicken-users] Re: dbus:send bug
From: |
Peter Bex |
Subject: |
Re: [Chicken-users] Re: dbus:send bug |
Date: |
Wed, 16 Mar 2011 19:34:39 +0100 |
User-agent: |
Mutt/1.4.2.3i |
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
- [Chicken-users] dbus:send bug, John J Foerch, 2011/03/15
- [Chicken-users] Re: dbus:send bug, John J Foerch, 2011/03/15
- Re: [Chicken-users] Re: dbus:send bug, Christian Kellermann, 2011/03/16
- [Chicken-users] Re: dbus:send bug, John J Foerch, 2011/03/16
- Re: [Chicken-users] Re: dbus:send bug, Mario Domenech Goulart, 2011/03/16
- Re: [Chicken-users] Re: dbus:send bug, Stephen Eilert, 2011/03/16
- Re: [Chicken-users] Re: dbus:send bug,
Peter Bex <=
- Re: [Chicken-users] Re: dbus:send bug, Stephen Eilert, 2011/03/16
- Re: [Chicken-users] Re: dbus:send bug, John Cowan, 2011/03/16
- Re: [Chicken-users] Re: dbus:send bug, Peter Bex, 2011/03/16
- Re: [Chicken-users] Re: dbus:send bug, Stephen Eilert, 2011/03/16
- Re: [Chicken-users] Re: dbus:send bug, Peter Bex, 2011/03/16
- Re: [Chicken-users] Re: dbus:send bug, John Gabriele, 2011/03/17
- Re: [Chicken-users] Re: dbus:send bug, Peter Bex, 2011/03/17
- Re: [Chicken-users] Re: dbus:send bug, Christian Kellermann, 2011/03/16
- [Chicken-users] Re: dbus:send bug, John J Foerch, 2011/03/16