From b81690522d5e6b4bd0682bc3a28fddefff79d0fb Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Wed, 11 Sep 2024 13:58:08 -0700 Subject: [PATCH] ;doc: CODE: notes on the use of haddock [#2222] --- doc/CODE.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/doc/CODE.md b/doc/CODE.md index ee50922a7..dd9bc18cf 100644 --- a/doc/CODE.md +++ b/doc/CODE.md @@ -214,3 +214,51 @@ Relevant tools include: [log](https://ircbrowse.net/day/hledger/2015/10/11) --> +## Code docs + +Haddock comments are the standard way of attaching docs (and sometimes small tests) +to a haskell definition. They are used pervasively in the hledger codebase. + +From [#2222](https://github.com/simonmichael/hledger/pull/2222): + +I tend to add a line of english description to most things. +They can be a big help to someone else debugging/improving code later. + +> *I use Haddock but I do not like to tell obvious things in Haddock comments. +> (And if there are surprising things I try to eliminate the surprises instead.)* + +I hear you! This is of course a recurring debate among programmers. + +I agree that obviously redundant haddocks that add no value are to be avoided. + +In the hledger codebase, there's no hard requirement for haddocks. +And sometimes the bar can be lower, eg in single-purpose less-frequently-developed modules like FODS.hs. + +But I believe it's always worth at least considering them when adding code, and it's something I consider when reviewing code. +I'll give some reasons why I think so, for the record (and maybe they'll persuade you just a little). + +Haddocks help guide and anchor the developer while writing or changing code. +They are the cheapest kind of doc, spec and test suite. +They also create a place to add actual doctests, now or later. + +Haddocks can be helpful to contributors who are not expert haskellers, which happens quite often in the hledger project. +The human language descriptions can complement the code, reducing cognitive effort and helping with mental chunking. +I think people find the hledger's code, with its pervasive haddocks, above average in readability. +(And I think we've had more successful contributions as a result.) + +Haddocks can also help experienced developers move faster. +Code which seems quite clear and obvious when you are writing it is often less obvious to oneself a few weeks or years later. +And certainly it can be less obvious to others than we might think. +When debugging or coding we are often mentally stretched and we would prefer to conserve brainpower for the main task. + +In my experience debugging/writing/changing hledger code, + +- Number of times I've regretted seeing a haddock comment attached to some code: almost zero. +- Effort to remove an excessive haddock: almost zero. +- Number of times I've been trying to understand some contributed code and haddocks would have saved my time: quite a few. +- Number of times I've appreciated code haddocks and found them helpful: many. +- Number of times I've found errors or staleness in haddocks: not often. +- Effort to fix wrong haddocks, or to write new ones: usually very low. And if it's high, it's usually very worthwhile because it alerts me to a confusion in the code or clarifies my thinking. + +hledger is a documentation-driven project, with docs in general being a top priority. +I think this is one reason it has held together and kept improving over a long period.