5 ms·
The Marginalia Manifesto
- jashkenas 16y agoBeautiful work, Fogus -- I hope it spurs a culture of Literate Clojure. One little point I'd like to make is that there's still a fairly strong difference between documentation and literate programming: Documentation is the material for users of the library, and literate programming is the material for readers of the code. Both are important, and neither should be left to chance.
- fogus 16y agoThanks for the kind words and the tip. I will try to keep the distinction clear as I proceed.
- pepijndevos 16y agoCare to give a tl;dr on literate programming?
- mahmud 16y agoCare to give a tl;dr on literate programming? No! Google it.
- steveklabnik 16y agoimagine if code and comments were inverted # def this_will work # 42 # end ---------- That's a tl;dr, but you really should Google. Short explanations about things that amount to "write longer and better explanations" bothers me in some meta way.
- sp332 16y agoInform 7 is a language (and IDE) for writing interactive fiction / text adventure games. Code actually is an English description of the game world and instructions to the runtime about behavior. The syntax is pretty limited of course, but it's completely readable for humans and computers. Check out this screenshot of a simple example game written in Inform 7: http://en.wikipedia.org/wiki/File:Inform_7_code_and_skein.png http://en.wikipedia.org/wiki/File:Inform_7_code_and_skein.pn...
- steveklabnik 16y agoI'm a big fan of inform 7; muds and Adventure were the reasons I'm a programmer today.
- jashkenas 16y agoSure. There's fullblown literate programming, which (arguably) has been practiced very rarely. For the scoop on that, check out Knuth: http://www-cs-faculty.stanford.edu/~uno/lp.html http://www-cs-faculty.stanford.edu/~uno/lp.html Here's an example of Adventure done up literate-style by Knuth: http://www.literateprogramming.com/adventure.pdf http://www.literateprogramming.com/adventure.pdf But what we're talking about here is a bit simpler. Writing code has always had this strange quality of having to write for two very different audiences at the same time. You need to address yourself both to the machine, to execute the code, and to human readers, to understand it. (Even if the human reader is only the author.) The entire history of programming languages and paradigms is a history of being able to address the human more and more directly, and the machine less directly, as computers get ever-more powerful and able to perform the extra legwork involved in translating "higher-level" forms. Literate programming means that you acknowledge this fact -- and try to write and structure your code to be read by people first and foremost. Think of your source code as an essay to be read, rather than a list of commands to be futzed with and hacked until it works.
- deleted 16y ago[deleted]
- deleted 16y ago[deleted]
- stuaxo 16y agoIs it bad I read this as The Mangina Manifesto ?