My main problem with literate programming is that it is difficult enough to keep short comments up to date vis-a-vis the code they describe. Longer comments wou

My main problem with literate programming is that it is difficult enough to keep short comments up to date vis-a-vis the code they describe. Longer comments would be even worse. Perhaps counter-intuitively, I have found the opposite to be the case so far. It’s all too easy to overlook a couple of small comments out of 20 when you update a screenful of code. You can’t really miss a whole paragraph of text that separates a few lines of code you’re working on from everything else. I’ve also found that with literate documentation the emphasis is naturally on explaining the big picture and why things are being done, and that kind of information tends to remain relevant through minor code changes anyway. You can still add short comments about particular points in the code as well, and maintaining those is much the same whether you’re using literate programming or not.