4 ms·

> We need something better than comments, or at the very least we need way better comment tech! One trick that I find very useful is the "Note" commenting con

by ufo 5y ago

> We need something better than comments, or at the very least we need way better comment tech! One trick that I find very useful is the "Note" commenting convention from the Glasgow Haskell Compiler. Basically, they add an easily-greppable title to important comments and then they can have one or more inline comments refer to that title. This low-tech hyperlinking keeps separate comments in sync. Also, programmers feel comfortable writing more complete comments because the main comment is not interleaved with the code, and therefore does not disrupt the reading flow of the surrounding code. For an example, scroll down to section 5.6: https://aosabook.org/en/ghc.html https://aosabook.org/en/ghc.html

nerdponx 5y ago
This is a great idea. I've already started writing long-ish-form block comments in files and functions with non-obvious design decisions, along with my initials and the date. I usually add a "NOTE" header of some kind, I'm going to start making sure this is easily grep-able in the future.
JoelMcCracken 5y ago
I've experimented with literate programming with org mode in emacs a few times, but every time its just been hard to make it stick. I don't really know why. I think it may have to do with the fact that its weird to have your project code in one giant file. I mean, you could do something differently than that I would think, but that's how I've always seen it. I actually just read the ghc chapter of aosa. Since then, I've been considering adopting this note style. It certainly seems like it could work out. For me, its clear that there is a lot of intrinsic information I would like to capture in some way, but it really doesn't work as self-documenting code. Some people say that stuff should go into commit messages, but I really think that has limited value. I dunno. I wish more people were working on this problem. I understand that unison has some kinda interesting takes on this, but I don't actually remember what they are off the top of my head.

by ufo 5y ago

nerdponx 5y ago

This is a great idea. I've already started writing long-ish-form block comments in files and functions with non-obvious design decisions, along with my initials and the date. I usually add a "NOTE" header of some kind, I'm going to start making sure this is easily grep-able in the future.

JoelMcCracken 5y ago

I've experimented with literate programming with org mode in emacs a few times, but every time its just been hard to make it stick. I don't really know why. I think it may have to do with the fact that its weird to have your project code in one giant file. I mean, you could do something differently than that I would think, but that's how I've always seen it. I actually just read the ghc chapter of aosa. Since then, I've been considering adopting this note style. It certainly seems like it could work out. For me, its clear that there is a lot of intrinsic information I would like to capture in some way, but it really doesn't work as self-documenting code. Some people say that stuff should go into commit messages, but I really think that has limited value. I dunno. I wish more people were working on this problem. I understand that unison has some kinda interesting takes on this, but I don't actually remember what they are off the top of my head.