Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Literate programming is much more than just commenting code

justinmeiners.github.io

Post reply on HN
Print view View original

21–30 of 112 posts

Re: Literate programming is much more than just commenting code

#21

Post by k__ »

goosedragons wrote: post #14
k__ wrote: post #6

Earlier quoted context omitted.

"Also are there any IDE plugins or error stack trace/debuggers for literate programming?" Good question! I always think it would be nice to just write Markdown sprinkled with code, but without IDE/editor support, it's dead in the water :(

R-studio supports this for R although you can sprinkle in other languages although they are 2nd class citizens unsurprisingly. Emacs has org-mode with babel that combined with poly-mode gets you every feature you'd expect in the major mode of the language you're writing in. Emacs also supports R-markdown/Sweave quite well.

Ah, yes I played around with R-studio last year.

Pretty nice experience.

Re: Literate programming is much more than just commenting code

#22

Post by k__ »

Yaina wrote: post #13
k__ wrote: post #10

Earlier quoted context omitted.

I wouldn't call it good. But better than nothing, I guess.

I think it's as good as it gets. The rough principal is there: You have one file, and you can derive the documentation and the program from it with different compilers. The idea of reading code like a book seems extremely flawed to me, and any attempts to create such languages either look like regular source code with slightly different syntax or are barely comprehensible (e.g. TeX)

I liked the idea of literate CoffeeScript.

It was basically Markdown and when executed, all but the code blocks was removed.

Made for a pretty nice file structure.

Re: Literate programming is much more than just commenting code

#23

Post by hzhou321 »

What are the key differences between a human audience and a machine interpreter? It is not the language or prose. It is the structure and order. For machines, details comes first. You declare all the actors and types with every non-forgiving annotations first. You may tuck the details into a header, but it still needs be ordered according to compilers and structured in the way that machines gets the details first. On the other hand, for human, it is top-down context oriented. The details are important, but not after we establish the right context.

So for literate programming, if you just think it is how you write the code (e.g. self-documenting or not), or you think it is the amount of commenting (e.g. doc string or not), if you are not first and constantly thinking about how to structure your code and establish context, you are not getting literate programming.

Now, once you understand your ends, the means (tangle or weave), will come along. It is easy to invent one if you don't have one. On the other hand, getting your coworkers to agree and work together, that's hard. It is easy to get machines to work together and it is easy for human to cope.

Re: Literate programming is much more than just commenting code

#24

Post by falcolas »

QuikAccount wrote: post #7

I like literate programming in theory but the most common response I see to it is that writing self documenting code is better because as you are working on a code base with many people, it is unlikely they will keep your prose up to date as the code is changed.

I think the one potential mitigating factor is that new features can be entirely new "chapters". Thanks to the tangling, a feature that needs to be added in 10 different places in the code can be written completely separately from the rest of the code.

Additionally, bugs can be fixed in-situ, refactoring can occur at will, and neither would require the prose around them to change, since code being talked about (despite moving or undergoing small changes) still fulfills the original, documented, purpose.

Re: Literate programming is much more than just commenting code

#26

Post by yumiris »

Literate programming has been particularly useful for my "dotfile" configurations, such as .emacs, .vimrc, .zshrc and even the .gitconfig file.

I use one .org file to declare all of my configurations, and tangle them together into the aforementioned files. This keeps things pretty portable, and makes up for the unintuitive readability of many dotfiles.

It can also work for rudimentary shell scripts and other single-file goodies; however, scaling it to proper multi-file programs proves to be difficult, especially when multiple developers are involved.

Re: Literate programming is much more than just commenting code

#28

Post by [deleted] »

hzhou321 wrote: post #23

What are the key differences between a human audience and a machine interpreter? It is not the language or prose. It is the structure and order. For machines, details comes first. You declare all the actors and types with every non-forgiving annotations first. You may tuck the details into a header, but it still needs be ordered according to compilers and structured in the way that machines gets the details first. On…

[deleted]

Re: Literate programming is much more than just commenting code

#29

Post by ravel-bar-foo »

falcolas wrote: post #24
QuikAccount wrote: post #7

I like literate programming in theory but the most common response I see to it is that writing self documenting code is better because as you are working on a code base with many people, it is unlikely they will keep your prose up to date as the code is changed.

I think the one potential mitigating factor is that new features can be entirely new "chapters". Thanks to the tangling, a feature that needs to be added in 10 different places in the code can be written completely separately from the rest of the code. Additionally, bugs can be fixed in-situ, refactoring can occur at will, and neither would require the prose around them to change, since code being talked about (despi…

It seems like adding new code as "Chapters," unless pursued with a bit of self-discipline, may result in spahgetti which is worse than a non-literate style.

Imagine a multi-person project where every little feature gets its own file, and now the programmer has to find the source of the bug between interacting blocks of in code fragments split across multiple files, ehich are combined together by tooling.... oh wait, I think that describes just about any sufficiently large C or C++ project.

Re: Literate programming is much more than just commenting code

#30

Post by ggm »

I have always felt a literate program is probably for many of us, a future deliverable on the hack we've implemented up front.

Very very few people can start from the abstraction and get TO a literate outcome without a lot of false steps along the way.

Or, as an alternative, the LOC of a literate program has to include the 100x cost of exploring how to carve it out of the block of mud we start from, including making our own tools.

Post reply on HN