;doc: CODE: notes on the use of haddock [#2222]

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.