4 ms·
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, wher
by vog 10y ago
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/matrix.org#view-matrix-generation 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.
- toxmeister 10y agoAuthor 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/src/dsl.org https://github.com/thi-ng/fabric/blob/master/fabric-facts/sr... https://github.com/thi-ng/geom/blob/develop/src/viz/core.org 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...