My program has man pages and now I'm wondering whether I should add a lot more comments to the code itself … maybe even turn it into some sort of literate programming artifact. Then again, I don't know. I haven't ever read good documentation of a program from beginning to end. It's either just simple function references, which is nice, but that already works, no extra required. Or I need to search the web for examples of how to use the functions where I don't understand the documentation. If that's the case, then it would be enough to just writer better documentation for packages and functions.
I guess I'm figuring out whether Knuth is right: "The practitioner of literate programming can be regarded as an essayist, whose main concern is with exposition and excellence of style. Such an author, with thesaurus in hand, chooses the names of variables carefully and explains what each variable means. He or she strives for a program that is comprehensible because its concepts have been introduced in an order that is best for human understanding, using a mixture of formal and informal methods that reinforce each other." I saw this quote in Jon Udell's Literate programming in Go where he talks about the code-as-wiki approach falling "far short of the standard set by Donald Knuth". https://www.infoworld.com/article/3677772/literate-programming-in-go.html
Add comment