[erlang-questions] Speaking of comments

[Masklinn]

On 2010-12-13, at 16:08 , Iñaki Garay wrote:
>>> On Wed, Dec 8, 2010 at 8:45 PM, Edmond Begumisa <ebegumisa@REDACTED
>>>> wrote:
>>> 
>>>> I've thought -- now and then, in the back of my mind -- about removing
>>>> comments from actual source all-together (for all languages) and instead,
>>>> putting them in companion files that the editor lines up side-by-side. More
>>>> like annotating than just traditional commenting.
> It was my understanding that this is called literate programming, as
> envisioned by Knuth, although he includes the comment markup in the
> same file as the code, and uses a preprocessor to extract either the
> documentation or the code.
> Knuth's original program was for C and is called CWEB.
That's exactly the reverse of literate programming: literate programming puts prose first and code second (so instead of marking up the comments, you mark up the code).

Knuth's own WEB (and CWEB) is extremely complex (out-of-order with macro expansions and hypertext references) and rather unlike usual program writing, a simpler literate idea can be found in Literate Haskell (lhs) where lines of code are prefixed (with `> `) and everything else is comment, yielding rather interesting executable documents.

Python also has something similar (though extremely reduced in scope) in its "doctests": code lines are prefixed with 4 spaces and sequentially executed, everything else is non-executable text. Doctests can be used either in docstrings (documentary comments, providing executable examples in the APIDoc) or as free-standing documents (documentation, papers, etc…).

The core idea stays the same: the core idea of literate programming is that the modules are first and foremost used to communicate with humans via prose, and the code is the second-class citizen.

As to edmond's idea of having code and comments side-by-side, he might be rather interested in Pycco [0] which produces literate-style documentation. Though it's a generator (it extracts and formats comments within the source file) it does produce something similar to what was described, and it seems to be erlang-compatible.

[0] http://fitzgen.github.com/pycco/