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.
Subscribe to:
Post Comments (Atom)
2 comments:
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.
-K
Thank you for sharing, it’s a nice value post shared. I enjoyed your site and I believe is a knowledgeable one. Thank you so much for sharing. villanova polytechnic hnd form out
Post a Comment