Proposal: require Haddock comment for every new top-level function and type in GHC source code

[Dominick Samperi]

Given the examples provided with this proposal it looks like this
change is targeted mostly at compiler hackers, and not at
library/package developers. For the latter community it would be nice
to establish a policy for libraries and packages that encourages
("nudges") developers to include comments
and examples, something more useful than type signatures or pointers
to the literature on type theory.

For example, the R stats system encourages package developers to
include examples, and these examples are run as part of the package
checking process, thus encouraging developers to keep the examples
up-to-date.

This kind of change might help Haskell move beyond its current role as
a research and teaching tool, and an incubator for new programming
ideas
that are eventually implemented and popularized in other programming
languages...

Cheers,
Dominick





On Fri, Jun 27, 2014 at 6:17 AM, Simon Peyton Jones
<simonpj at microsoft.com> wrote:
> I'd be OK with this, (it's a bit like requiring signatures on all top level
> functions) but I don't know how we'd enforce it.
>
>
>
> Do you think the requirement should be for all top-level functions or just
> exported ones?
>
>
>
> I agree that Notes have a different purpose.  But it should be OK style to
> refer to a Note from a top-level function comment, even though Haddock won't
> be able to make much sense of it.
>
>
>
> Simon
>
>
>
> From: ghc-devs [mailto:ghc-devs-bounces at haskell.org] On Behalf Of Johan
> Tibell
> Sent: 27 June 2014 10:51
> To: ghc-devs at haskell.org
> Subject: Proposal: require Haddock comment for every new top-level function
> and type in GHC source code
>
>
>
> Hi!
>
>
>
> I found myself exploring new parts of the GHC code base the last few weeks
> (exciting!), which again reminded me of my biggest frustration when working
> on GHC: the lack of per-function/type (Haddock) comments.
>
>
>
> GHC code is sometimes commented with "notes", which are great but tend to
> (1) mostly cover the exceptional cases and (2) talk about the implementation
> of a function, not how a caller might use it or why.
>
>
>
> Lack of documentation, in GHC and other software projects, usually has (at
> least) two causes:
>
> Programmers comment code they think is "complex enough to warrant a
> comment". The problem is that the author is usually a poor judge of what's
> complex enough, because he/she is too familiar with the code and tends to
> under-document code when following this principle.
> Documenting is boring and tends to have little benefit the person writing to
> documentation. Given lack of incentives we tend to document less than we
> ought to.
>
> I've only seen one successful way to combat the lack of documentation that
> stems from the above: have the project's style guide mandate that top-level
> functions and types (or at least those that are exported) have
> documentation. This works well at Google.
>
>
>
> Anecdote: we have one code base inside Google that was until recently exempt
> from this rule and documentation is almost completely absent in that code
> base, even though hundreds of engineers work on and need to understand it
> every day. This breeds institutional knowledge problems i.e. if the author
> of a core piece of code leaves, lots of knowledge is lost.
>
>
>
> Proposal: I propose that we require that new top-level functions and types
> have Haddock comments, even if they start out as a single, humble sentence.
>
>
>
> I've found that putting even that one sentence (1) helps new users and (2)
> establishes a place for improvements to be made. There's a strong "broken
> window" effect to lack of comments, in that lack of comments breeds more
> lack of comments as developers follow established practices.
>
>
>
> We should add this requirement to the style guide. Having it as a written
> down policy tends to prevent having to re-hash the whole argument about
> documentation over and over again. This has also helped us a lot at Google,
> because programmers can spend endless amount of time arguing about comments,
> placement of curly braces, etc. and having a written policy helps cut down
> on that.
>
>
>
> To give an idea of how to write good comments, here are two examples of
> undocumented code I ran into in GHC and how better comments would have
> helped.
>
>
>
> First example
>
> In compiler/nativeGen/X86/Instr.hs there's a (local) function called mkRUR,
> which is a helper function use when computing instruction register usage.
>
>
>
> The first question that I asked upon seeing uses of that function was "what
> does RUR stand for?" Given the context the function is in, I guessed it
> stands for read-update-read, because R is used to mean "read" in the
> enclosing function and "updating" is related to "reading" so that must be
> what U stands for. It turns out that it stands for RegUsageReadonly. Here's
> a comment that would have captured, in a single sentence, what this function
> is for:
>
>
>
>     -- | Create register usage info for instruction that only
>
>     -- reads registers.
>
>     mkRUR src = src' `seq` RU src' []
>
>         where src' = filter (interesting platform) src
>
>
>
> That already a big improvement. A note about the register filtering, which
> means that not all registers you pass to the function will be recorded as
> being read in the end, could also be useful.
>
>
>
> Aside: providing a type signature, which would have made it clear that the
> return type is RU, might also have helped in this particular case.
>
>
>
> Second example
>
> In the same file there a function called x86_regUsageOfInstr. It's the
> function that encloses the local function mkRUR above.
>
>
>
> I could figure out that this function has something to do with register
> usage, of the instruction passed as an argument, and that register usage is
> important for the register allocator. However, trying to understand in more
> detail what that meant was more of challenge than it needed to be. First, a
> comment more clearly explaining what computing register usage means in
> practice would be helpful:
>
>
>
>     -- | Returns which registers are read and written by this
>
>     -- instruction, as a (read, written) pair. This info is used
>
>     -- by the register allocator.
>
>     x86_regUsageOfInstr :: Platform -> Instr -> RegUsage
>
>
>
> The reason mentioning that the return value is essentially a (read, written)
> pair is helpful is because the body of the function a big case statement
> full of lines like this one:
>
>
>
>     GCMP _ src1 src2 -> mkRUR [src1,src2]
>
>     ...
>
>     FDIV _ src  dst  -> usageRM src dst
>
>
>
> It's not immediately clear that all the various helper functions used here
> just end up computing a pair of the above form. A top-level comment lets you
> understand what's going on without understanding exactly what all these
> helper functions are doing.
>
>
>
> Thoughts?
>
>
>
> -- Johan
>
>
>
>
> _______________________________________________
> ghc-devs mailing list
> ghc-devs at haskell.org
> http://www.haskell.org/mailman/listinfo/ghc-devs
>