Your form has successfully submitted

One of our teammates will get back to you soon.

The Notes of GHC

The Notes of GHC

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.

Published on: May. 18, 2015

Written by:

Software Developer

Juan Pedro Villa

Subscribe to our blog

Join our community and get the latest articles, tips, and insights delivered straight to your inbox. Don’t miss it – subscribe now and be part of the conversation!

We care about your data. Check out our Privacy Policy.