Simon Peyton Jones on Notes in source code (2021)

[Transcript below. This is from an interview with Simon Peyton Jones on the podcast Functional Futures.]

JM: John Mostovoy
SPJ: Simon Peyton Jones
VZ: Vladislav Zavialov

SPJ: I want to mention one other piece of programming practice which is completely not to do with functional programming but we use all over GHC and which I’ve never seen anywhere else which is using these Notes.

SPJ: Often you comment code, if the comment is a subtle one the comment grows, and suddenly you can’t see the code anymore because the comment is too long. So we´ve just adopted this terribly simple practice of saying – in the code, you say “See Note” and then you put square brackets, and then you put a title for the note. And elsewhere, in that same module typically, you will put the note with a heading and an underline and then some English-language text.

SPJ: GHC has hundreds or thousands of these notes and I read them and write them all the time. They are messages to my future self. And I read my own notes that I wrote 15 years ago and I think ‘ahhh, that’s clever’ because essentialy I would have gone to that code, if it hadn’t been for the note I would have changed it – wrongly!

SPJ: I’ve never seen this, it’s such a simple idea It’s so widely used in GHC and I’ve never seen it anywhere else. So I just thought I’d mention it because it seems like, well, in any language I would now do this. It’s a bit like literate programming. It’s like a very low-tech literate programming.

VZ: Indeed it is great, and when I was starting with GHC contribution I read lots of notes in the source code and they were of great help to me. So I wish more projects adopted this practice which GHC pioneered.

JM: That’s a good point, especially the point that you can’t see the code sometimes between big comments. Especially when it comes to Heredocs and inline tests.

SPJ: Yes, that’s right. And sometimes the note that you’re referring to might be – might be – 50 lines long. And you don’t want to be inhibited when you’re writing it by thinking ‘ahhh, this is a comment between, you know, an if and a then !’ That’s crazy. Why, you shouldn’t be inhibited in that way. I want the note to explain the example and give the context and point to tickets, and all of that. I think a little bit of IDE support would be good. So you can click on a note and go to its definition. But we’ve never done that.

12
Sietsebb 12 days ago
Oh, an example of a Note might be useful here. Here is the first example from the GHC coding style guidelines, section Using Notes.

The note:
```
  Note [Equality-constrained types]
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  The type   forall ab. (a ~ [b]) => blah
  is encoded like this:

     ForAllTy (a:*) $ ForAllTy (b:*) $
     FunTy (TyConApp (~) [a, [b]]) $
     blah
```
Referring to the note:
```
 data Type
   = FunTy Type Type -- See Note [Equality-constrained types]
   | ...
```
1. 2
  
  oger 12 days ago
  
  So, for clarification: is the note text typically in the same file as the code? At the top, or bottom? Or is it in a separate file, e.g. in one large “notes.md” file?
  1. 3
    
    fanf 12 days ago
    
    There are several notes in https://gitlab.haskell.org/ghc/ghc/-/blob/master/compiler/GHC/HsToCore/Utils.hs
6

Sietsebb 12 days ago

I’d like to thank Alexis King, who talked about GHC’s Notes method (and more!) on Software Unscripted – it’s thanks to her that I learned of this Notes idea.

If you want to use Notes in your own source code, you can just start doing it – my impression was that GHC used to use it without any special tooling.

If you want some integrity checking, Tagref checks that references refer to existing tag titles, and that tag titles are unique. Works with any programming language.

GHC’s notes, collated and published at Readthedocs by myuon.

The’res a Using Notes section in GHC’s coding style guidelines.
2

hc 12 days ago

it might be fun to use markdown footnote syntax [^footnote] for that

[^footnote]: in some markdown systems (but not the one used on lobste.rs), you can reference a footnote using [^label] syntax, and then prefix the footnote with [^label]: elsewhere in the document
1. 2
  
  fanf 12 days ago
  
  I think those footnotes are a Pandoc extension: they aren’t in Commonmark or GFM.
  1. 1
    
    hc 11 days ago
    
    github supports them. are they using pandoc?
    1. 3
      
      fanf 11 days ago
      
      Their spec says footnotes are not supported https://github.github.com/gfm/ but, oh sigh, https://github.blog/changelog/2021-09-30-footnotes-now-supported-in-markdown-fields/ they aren’t maintaining their documentation properly. Good grief.
2

janus 12 days ago

Old GHC releases also used Literal Haskell (LHS) syntax for most files. In LHS, your program is contained in \begin{code} blocks. So they were LaTeX.

idris2 supports the same, but for markdown. I’ve extended it to support Scribble, which is for Scheme.