4 ms·

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, m

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 13y 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 13y 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/ ?

mistercow 13y 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 13y 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/ ?