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. Comments