Thursday, June 23, 2005

Literate programming

It's tempting to use literate programming to write a little document recording every last implementation decision you made in designing a library, and that kind of dedication to documentation is admirable, but it's ultimately misdirected.

Javadoc has the better idea: couple the documentation of the interface with the code. I'm beginning to believe that lower-level design decisions should be documented elsewhere, and should be written on a by-need basis only. Code is hard enough to maintain, but documenting every last aspect of your code just guarantees the documentation will get out of date. Often the design decisions are global anyway, in which case there isn't any one place in the code where they really belong.


Kaushik said...

I think Javadoc (or doxygen) and literate programming have different goals. Javadoc is what you need when you have to figure out how to use a library written by someone else. On the other hand literate programming is great when you want to understand a program "from the inside".

Literate programming gives you insights into the design process itself. It records low-level assumptions made and alternatives considered but rejected -- these are things that would otherwise be lost. Open source is great and all, but you see only the finished product; as someone interested in understanding a program (rather than just using it), I'd rather see "the making of" version than the theatrical release.

Also, a (well written) literate program suggests a sequence in which you can go about reading and understanding the code. Javadoc draws you a broad picture, but it is often not obvious where to begin and how to proceed.

Quite apart from generating external documentation, literate programming has another benefit that I believe is quite important: it helps you think, as a programmer and designer, in a more systematic manner. It helps (forces?) you to organize your thoughts clearly, since you have to make it all explicit by writing it down. Note that the benefit that literate programming offers here, is more in the writing than in the reading and understanding of programs.

That said, I agree that lower-level design decisions should be documented separately from interface documentation. I wonder if it would be feasible to develop a system wherein you can write the program LP-style, but generate the interface documentation and (a more introspective) implementation documentation separately.


timmykeels said...

I Personally Like Your Post; You Have Shared Good Insights And Experiences. Keep It Up.
Do check
Paypal Login
gemini login

jack peterson said...

Hello very cool site!! Man .. Excellent .. Superb .. I’ll bookmark your blog and take the feeds additionally¡KI am glad to search out so many helpful info right here within the post, we want develop extra strategies in this regard, thank you for sharing. . . . . .
Do check
Telstra email login

Kaylee Brown said...

Generally, programming assignments are charged differently from other assignments, but the charging procedure is as usual from the programming assignment help services. Programming assignments are not easy and for a beginner, they are quite tough. If you are searching for programming assignment help for your institute, you need someone who knows the subject. Students do not get enough time to handle such assignments. Programming assignments require a lot of concentration and basic knowledge. Handing over your project assignment to some expert would be the best idea. Lots of assignment writing agencies are available in your locality. You just need to secure that you have landed on the page of the best assignment writing agencies in the locality.