[darcs-users] Code documentation (Was: Re: darcs patch: Add comments ...)

Petr Rockai me at mornfall.net
Mon Mar 30 14:34:01 UTC 2009

Eric Kow <kowey at darcs.net> writes:
> With David's warnings about the dangers of code comments being a
> liability, I hope that our push for more haddocks is a good thing.  I
> still think it does, if we think of it as API-writing.  Not trying to
> say what the functions do, but what they're for, and what gotchas to
> look out for.
For what it's worth, I have taken a (for me) somewhat unorthodox stance on
documenting code with hashed-storage. My *usual* approach is to write lots of
code and only write comments for the most obscure features of the code.

What I am doing now as well is this:

-- | A design blurb for foo, in form of a hopefully-useful API doc.
foo :: Bar -> Baz
foo = undefined

It seems to help with getting a better picture of how foo is going to be used,
where it fits, etc.

Of course, what also happens is that those comments get out of date, as new
functions get written and old ones need to be twisted a little (or a lot) to
fit the new picture. However, it's turning out that this is not such a problem,
with relatively cohesive and small codebase that hashed-storage is. Of course,
this problem is much more pronounced in large, sprawled codebase like darcs is.

In an ideal world, we (the darcs team) would chop up the codebase into smaller
chunks and assume responsibility over those. This would naturally extend to
documentation. Spinning off libraries only helps with that (and I'll try to
make hashed-storage an example of how it's much better for darcs to work more
like that).


Peter Rockai | me()mornfall!net | prockai()redhat!com
 http://blog.mornfall.net | http://web.mornfall.net

"In My Egotistical Opinion, most people's C programs should be
 indented six feet downward and covered with dirt."
     -- Blair P. Houghton on the subject of C program indentation

More information about the darcs-users mailing list