I recently wrote a post about how I was using Literate Programming principles in Org-mode to write the unit tests of my applications side-by-side with the code it tests. I got some good feedbacks about the post, however one that particularly caught my eye is a blog post on the Irreal blog which states:
One possible problem with this procedure is if you’re working in a team and not everyone is an Emacs user. Non Emacs users won’t be keen to tangle an Org document to get the code and probably won’t feel comfortable making changes to an Org file. Unless everyone you’re working with is an Emacs user or you’re working alone, this means that Giasson’s workflow will have to be limited to initial development. Still, it’s a powerful technique and well worth experimenting with.
It is not the first time I have read such observation about Literate Programming (and Org-mode & Emacs). This is certainly a right and legitimate concern. Literate Programming is a set of concepts and principles with two actions at its core: weaving (generating human readable version of the application) and tangling (generating the computer code of the application) [a literate document]. The literate document has to comply with some syntax to determine what needs to be weaved and what needs to be tangled. This syntax needs to be implemented in a development environment to be usable. It could be fully integrate (like with Org-mode) or part of a development workflow (like CWEB). It is for this reason that there may be a possible problem: because the way to write a software application is inherently different than how we learned to program and it requires some specific development environments or workflows. This is fine if there is only one developer on the application or only a few that already use the same environment.
The real concern arises when Literate Programming with a specific Development Environment is forced upon an existing [potentially large] team of developers. The nature of humans, the diversity of backgrounds, knowledge and personalities would probably doom such a project. The willingness won’t be the same, some won’t want to learn a new way to program, etc.
However not all situations are the same. If a new team needs to be hired, then the task is completely different. The skills required to develop using the Literate Programming paradigm, or more importantly their willingness to learn these new skills, could be central to the selection process.
Emerging architectures like Micro-services may also help adopting Literate Programming in existing projects. Micro-services architecture enables all kind of web services, developed in all kind of languages, to interact together like if it was a monolithic application. In such a setup, the code of already developed micro-services could remain the same and then new micro-service initiatives could be developed using Literate Programming by a dedicated person, or a small dedicated team without affecting any other development teams. The usage of these new development techniques would be constrained to these new micro-services projects.
However I am conscious that Literate Programming is a new development paradigm that needs much effort, concentration and willingness to adopt. It changes the core development process of a developer which can be quite destabilizing and daunting. It is a shift in development culture that is required here. This is not a simple and easy thing. This is why I agree that team development using Literate Programming is a legitimate concern to have.
However, I am finding that the benefits of this cultural shift outweigh the initial investment that is required (and which is non-trivial). That is why I will continue to document the way I develop my new applications in Literate Programming using Org-mode and to explain all of the benefits I am seeing and the issues I may face.
In mean time, if you are interested in Literate Programming, I would strongly suggest you to take 30 minutes to listen at Thimoty Daly‘s Literate Programming in the Large talk:
Another work I want to highlight is Karsten Schmidt‘s work at thi-ng. All of his projects are using Org-mode. His biggest project is geom which has hundred of stars, 22 forks and 6 contributors which suggest that Org-mode is not a show stopper to create a healthy opensource project.
jcs
June 10, 2016 — 3:13 pm
Just to be clear, I really like your approach. The problem that I was writing about is not Literate Programming but the fact that the approach depends critically on Org mode and Emacs. Given the strong feelings that most developers have about their editors, this can be a problem for teams where some engineers use vim or even one of those other editors.
Literate programming with, say, CWEB doesn’t present the same problems since the program can be written with any editor and the tangling can be done in the make file.
OTOH, your approach is attractive enough that it could persuade the users of other editors to give Emacs a try and bring them into the light.
Frederick Giasson
June 12, 2016 — 8:45 am
Hi jcs!
Sure, I understand and I agree with this “critic”. In fact, it is not a critic but a reality, in my opinion. The problem is that barely any editor at the moment does support this kind of development. To me doing literate programming in Org-mode, or CWEB is the same, you do have some syntax to do the weaving and tangling. About Org-mode, it sure is mostly exclusively Emacs. However there are other initiatives like the Vim Org-mode plugins that should do pretty much the same (never tried it). I don’t see why Org-mode couldn’t be implemented in other editors as plugins. The issue is that there is probably no insensitive to do so.
Another note about Emacs, what is really attractive is the number of languages it supports, and the number of languages already supported by Org-mode.
But in any case, with the current state of the LT ecosystem, this is a big hurdle to overcome.
Thanks for weighing in!