geom

Author here: Agreed & most parts of this particular project aren't really the best example. With other (newer) projects I embraced the LP style much more, and in fact by now really often first write the prose parts to get my head clear about a certain aspect and only then start writing code, e.g. https://github.com/thi-ng/fabric/blob/master/fabric-facts/sr... https://github.com/thi-ng/geom/blob/develop/src/viz/core.org As for the docstrings included in the core, this is largely to address complains from other users, who are used to have docs available in the REPL and I often don't have the resources/time to provide both org-mode and docstrings...

I see that this is a honorable goal, but in this particular project the source looks more like source than documentation. An extreme example is this part, where the code even contains function docstrings, rather than having the docstring as part of the surrounding document: https://github.com/thi-ng/geom/blob/master/geom-core/src/mat... This is an effect which I observed with my own literate programming attempts, too: They quickly end up with large documents that contain lots of code listings and not much explaination.

Literate programming is a thing that's long piqued my interest, but it usually seems more suited to academic or personal use. Having said that, a beautiful example of LP in the wild is geom[0], a Clojure/Clojurescript library written entirely in org-mode. Browsing through the source, I have to keep reminding myself that I'm looking at the code and not just the documentation. [0] https://github.com/thi-ng/geom

Literate programming with the source code in Emacs org-mode. Example of raw source: https://raw.githubusercontent.com/thi-ng/geom/master/geom-ty... Shows up on Github as: https://github.com/thi-ng/geom/blob/master/geom-types/src/be...

toxi's thi-ng/geom[1] library deserves a mention in this space. [1]: https://github.com/thi-ng/geom