Eric Kow <[email protected]> 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). Yours, Petr. -- 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 _______________________________________________ darcs-users mailing list [email protected] http://lists.osuosl.org/mailman/listinfo/darcs-users
