In the GHC chapter of The Architecture of Open Source Applications, Simon Marlow and Simon Peyton Jones give an overview of the architecture of GHC, and discuss some ideas which can be useful for writing better programs.
In particular, they talk about a very simple solution to two common problems that arise with the use of long implementation comments:
-
long comments interleaved with the code can make the code less readable, and
-
long comments detached from the code can be easily ignored, or become out of date, obsolete, or even misleading.
Basically, instead of writing a long implementation comment either interleaved with or detached from the code, Marlow and Peyton Jones (and the GHC Haskell style guide) suggest that the programmer can add a note and reference it wherever it is relevant.
For example, in the GHC.Base module, there is one such
note explaining the import of the GHC.Tuple module:
import GHC.Tuple () -- Note [Depend on GHC.Tuple]
...
{-
Note [Depend on GHC.Integer]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
...
Note [Depend on GHC.Tuple]
~~~~~~~~~~~~~~~~~~~~~~~~~~
Similarly, tuple syntax (or ()) creates an implicit dependency on
GHC.Tuple, so we use the same rule as for Integer --- see Note
[Depend on GHC.Integer] --- to explain this to the build system.
We make GHC.Base depend on GHC.Tuple, and everything else depends
on GHC.Base or Prelude.
-}
This is a very simple example, but the notes of GHC often include references to specific issues or test cases. It's a very basic convention, but the GHC folks claim that is has transformed their lives.
Not only is this technique helpful for other programmers who need to read your code, but writing long implementation comments in notes is great for writing better comments which make you reason about your code in order to identify ways to refactor it. Definitely worth it.
