Why not write a Markdown doc that compiles to code? Especially with a system like Rails, where so much can be auto-generated. Obviously this isn't for mission-critical or new ideas, but for putting your CRUD app into the world, it makes total sense.
Why not write a Markdown doc that compiles to code? Especially with a system like Rails, where so much can be auto-generated. Obviously this isn't for mission-critical or new ideas, but for putting your CRUD app into the world, it makes total sense.
Those consultants have moved on to selling some new fantasy. I'm still here writing code.
What was different in Eve was that the entire language was unordered, and thus you don't need a tool-chain to read literate source -- the raw source itself is literate.
Haskell will recognize a .lhs extension and do comments by default, using > to prefix lines that are actual code (looks block-quote like).
Frankly I am something of a skeptic of literate programming. In most of the literate source code I've read, the code is clearer than the prose anyway, and having every detail in comments just makes the whys and the high level design harder to find.
My approach is to basically assume the reader is familiar with the language and the key libraries, document the whys, overall design, and the api contracts, and try to pick good variables and write clear code. This is not to say "inline comments are bad," but I find that usually when I find myself writing a lot of comments explaining the details it's because I'm writing a lot of confusing code.