On Sunday 06 September 2009 03:52:29 Dana Hudes wrote: > In regards inline POD: the technique is called literate programming. > Documentation with code. An early such system was developed by Donald E. > Knuth called Tangle and another component called Weave. >
Well, as good inline POD is (and I like it) it is a far cry from literate programming: http://www.perl.com/pub/a/tchrist/litprog.html (by MJD - not by Tom Christiansen). You can do Literate Programming in Perl, just not only with POD. POD is meant to document interfaces (command line interfaces, APIs, etc.) - not to explain the code and how it does it (or to restructure the code appropriately). I should note that I've expressed some sentiments against Literate Programming and other "Mountains of Documentation" methods here: http://www.shlomifish.org/philosophy/computers/software-management/perfect- workplace/ (short URL: http://shlom.in/perfect-workplace ) The sentiments I expressed there were not original and actually were borrowed from Extreme Programming and other previous places. However, I can attest from my experience that even inline comments often become out-of-date. While I support writing some documentation, I think that it is easier, and more rewarding to make sure code has good automated tests coverage (where tests serve as a kind of spec to the code), and is factored out well (using "Extract Function/Method" and other refactorings) to be self-documenting. Regards, Shlomi Fish > > Sent from my BlackBerry® smartphone with Nextel Direct Connect > -- ----------------------------------------------------------------- Shlomi Fish http://www.shlomifish.org/ "The Human Hacking Field Guide" - http://shlom.in/hhfg Chuck Norris read the entire English Wikipedia in 24 hours. Twice.
