3 ms·

Since CoffeeScript started supporting literate programming, I've enjoyed dabbling with it quite a lot. I wrote a program to generate a recipe for a variant on t

Since CoffeeScript started supporting literate programming, I've enjoyed dabbling with it quite a lot. I wrote a program to generate a recipe for a variant on the "soylent" concept, using numeric.js to solve and optimize for various constraints based on a target nutritional profile. The goal of that was rather close to what TFA is discussing; I had previously computed the recipe by hand, realized later that my calculations were wrong, and decided to build the recipe as a well-documented reproducible computation instead of an opaque final result. But what I have not found yet (or discovered for myself) is good guidance on how to document larger blocks of code. If a function is more than a few lines long, I haven't found a satisfactory way to document it. The first approach I tried was not to respect the atomicity of the function in terms of formatting. That is, I would just write along literately about what the function was doing, right inside the function. The problem is that in both the code and the generated documentation, it becomes very difficult to discern scope visually. The second approach I tried was to give a brief overview description above the function, then include ordinary comments inside it. That's fine and all, but at that point, you're not gaining much over simple block comments above the function. The third approach I've tried is to either use an ordered list of steps preceding the function, or to describe the function with numbered footnotes, and then to add corresponding numeric comments in the code. This is the most satisfactory solution I've found yet, and the documentation ends up looking like a programming book. But the locality of reference is just terrible. It's also just terrible for control flow statements. Using an outline format instead of an ordered list can allow for a bit better control flow, but it's still not great.

jasongrout 14y ago
Would it make a difference if your editor had better support for these sorts of things? For example, collapsed comments, where its shows only the first line, might help a lot. Then you could put a summary in the first line and elaborate in a paragraph that would be hidden by default. Or what if the editor supported such comments in the margin, like the LibreOffice or Word review comment features?
- mistercow 14y ago
  The problem really isn't that the description is too long, though. The problem is that you have to jump back and forth to see what part of the explanation applies to what part of the code. I'm also wary of making code readability too dependent on a specific editor The other problem with using numeric footnotes is that any time you change the code, you have to laboriously renumber the comments. That part really could be helped with better editor support. And if the generated documentation were, say, a rich HTML page, you could even have it so that mousing over a line of code would highlight the relevant point in the documentation (and vice versa). But LP has been around a lot longer than I have been programming at all, and I find it hard to believe that after a month of dabbling, I have better insights into improving it than those who have been using it for decades. That said, the more I read into LP, the more I feel like part of my problem may simply be that CoffeeScript's implementation of it is rather anæmic. Traditional LP is apparently supposed to have macros that are essentially section headers that double as language constructs. That's a lot more powerful than just stripping everything but the code blocks from a markdown file and executing the result.
  - eru 14y ago
    Yes, traditional literate programming is a bit more powerful than what you get with CoffeeScript. Have you tried reading the examples at http://www.literateprogramming.com/ http://www.literateprogramming.com/ ?
datr 14y ago
Documentation generator templates which split the comments and the code help with the scope problem of solution 1. E.g.: http://reload.github.io/phing-drupal-template/ http://reload.github.io/phing-drupal-template/ The trade off being that the vertical spacing of the code is now inconsistent.
- mistercow 14y ago
  That does certainly help in terms of making the documentation readable, but it doesn't help the readability of the source code.

jasongrout 14y ago

Would it make a difference if your editor had better support for these sorts of things? For example, collapsed comments, where its shows only the first line, might help a lot. Then you could put a summary in the first line and elaborate in a paragraph that would be hidden by default. Or what if the editor supported such comments in the margin, like the LibreOffice or Word review comment features?

mistercow 14y ago
The problem really isn't that the description is too long, though. The problem is that you have to jump back and forth to see what part of the explanation applies to what part of the code. I'm also wary of making code readability too dependent on a specific editor The other problem with using numeric footnotes is that any time you change the code, you have to laboriously renumber the comments. That part really could be helped with better editor support. And if the generated documentation were, say, a rich HTML page, you could even have it so that mousing over a line of code would highlight the relevant point in the documentation (and vice versa). But LP has been around a lot longer than I have been programming at all, and I find it hard to believe that after a month of dabbling, I have better insights into improving it than those who have been using it for decades. That said, the more I read into LP, the more I feel like part of my problem may simply be that CoffeeScript's implementation of it is rather anæmic. Traditional LP is apparently supposed to have macros that are essentially section headers that double as language constructs. That's a lot more powerful than just stripping everything but the code blocks from a markdown file and executing the result.
- eru 14y ago
  Yes, traditional literate programming is a bit more powerful than what you get with CoffeeScript. Have you tried reading the examples at http://www.literateprogramming.com/ http://www.literateprogramming.com/ ?

datr 14y ago

Documentation generator templates which split the comments and the code help with the scope problem of solution 1. E.g.: http://reload.github.io/phing-drupal-template/ http://reload.github.io/phing-drupal-template/ The trade off being that the vertical spacing of the code is now inconsistent.

mistercow 14y ago
That does certainly help in terms of making the documentation readable, but it doesn't help the readability of the source code.