
The Marginalia Manifesto - mattyb
http://blog.fogus.me/2011/01/05/the-marginalia-manifesto/
======
jashkenas
Beautiful 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.

~~~
pepijndevos
Care to give a tl;dr on literate programming?

~~~
steveklabnik

        imagine 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
Inform 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.pn...](http://en.wikipedia.org/wiki/File:Inform_7_code_and_skein.png)

~~~
steveklabnik
I'm a big fan of inform 7; muds and Adventure were the reasons I'm a
programmer today.

------
stuaxo
Is it bad I read this as The Mangina Manifesto ?

