HACKER Q&A
📣 jnxx

What do you think about literate programming for handover/legacy code?


What are your experiences with literate programming for handover of code?

I am thinking of tools like noweb (https://en.wikipedia.org/wiki/Noweb), LEO (http://leoeditor.com/), Emacs org-mode (http://cachestocaches.com/2018/6/org-literate-programming/), scribble/lp2 (https://docs.racket-lang.org/scribble/lp.html#%28part._scribble_lp2_.Language%29),

My experience so far is that it can be a fantastic tool for documenting and handing over complex algorithms to successor developers. I extensively use personal wikis (sometimes MoinMoin, sometimes Zim Wiki, in the last time often a combination of github with reStructuredText) for work. That might also be sufficient when handing over boring code. But when handing over complex stuff which is based on some well-pondered ideas and heavily negotiated hardware protocols, I think a linear narrative is the best way to lay out and communicate these ideas.

Even if the successor decides not to use the literate tools, he has documented code to start with.

I have also good experiences with using literate programming for understanding complex code and core algorithms that have been given to me without documentation (be it that documentation was not valued that much in the organization, that somebody just had left in disagreement or, in one extreme case, that an important contractor actually died, and his family was unwilling to hand over any notes).

However, what I also found is that when code is severely lacking documentation, this points, in most cases, to a deeper problem with the organization: It might be micro-management, or serious overload of key developers, or simply unwillingness to allocate resources for such things as code quality, which in turn might be based on serious false assumptions what are key products and key efforts in software development. My experience in this case is you can't fix that with tools.


  👤 orionblastar Accepted Answer ✓
I used to convert Clipper for DOS programs to VBA in MS Access for faster processing and user friendliness. I used to translate COBOL to Classic Visual BASIC. I do it line per line in translating in my head.

At the law firm I worked at for 4 and a half years I was made Legacy Software Programmer by taking over old projects and converting them to new technology so they can run on faster machines.