Programming

21417 readers

338 users here now

Welcome to the main community in programming.dev! Feel free to post anything relating to programming here!

Cross posting is strongly encouraged in the instance. If you feel your post or another person's post makes sense in another community cross post into it.

Hope you enjoy the instance!

Rules

Follow the programming.dev instance rules
Keep content related to programming in some way
If you're posting long videos try to add in some form of tldr for those who don't want to watch videos

Wormhole

Follow the wormhole through a path of communities [email protected]

founded 2 years ago

MODERATORS

[email protected]

Literate Programming (www.literateprogramming.com)

submitted 4 days ago* (last edited 4 days ago) by [email protected] to c/[email protected]

11 comments fedilink hide all child comments

This is the name of a concept to combine source code and highly structured human-readable documentation, such that the main artefact is the documentation, and the secondary artefact the full source code extracted from it. Any change to the source means changing the explanatory documentation of the goals and reasoning at the same time. It was invented by no other than Don Knuth, and he, together with his collaborators, wrote the TeX program in it, to show how it is useful in practice.

I myself have used the technique in various occasions at work, for example when taking on an important but almost unreadable piece of code I inherited at work, to preparing sources for a complex algorithm for handover when I was leaving another larger project, and also in leisure coding.

The tool which is most widely used for this approach today is Emacs org-mode. It has the advantage that it works for every programming language, and you will likely find full examples for all languages you use, but many other tools (for example for vim) exist.

you are viewing a single comment's thread
view the rest of the comments

[–] [email protected] 4 points 3 days ago (2 children)

I've tried this a few times. I don't think it works.

Basically the way you want to explain a piece of reasoning , and the order in which things need to be defined for a program, are different. You end up either making the document match the code structures, or the code structure match the document. Both are bad.

[–] [email protected] 2 points 3 days ago* (last edited 3 days ago) (1 children)

Literate programming tackles exactly that: You write the documentation in explanation order, and the code gets assembled in the order of a well-structured program. Have a look at the examples how this works.

[–] [email protected] 2 points 2 days ago

It's not immediately obvious to me where the examples are.