Greetings all, Our usual goal for our Perl software is to have it find its way into CPAN, so that the whole Perl community can find it and use it. This requires we do a few things, one is to use object oriented Perl and create modules, another is to have good test cases that run automatically with "make test", and another is that we have nice clean POD (plain old documentation) that everyone can see and read. CPAN is nice because it encourages all of the above and more in there interests of promoting code re-use.
In POD (or perldoc as we sometimes call it), there are typical "sections" in code that are used, and these are described here : http://perldoc.perl.org/perlmodstyle.html#DOCUMENTING-YOUR-MODULE Even in simple programs that aren't object oriented we should always follow this style (to build good habits :) If you look at CPAN.... http://search.cpan.org most of the modules contained therein use this style - that's the style we want to use as well (with those same sections and same level of commentary). Then, in your code you should also try to have more detailed comments regarding what is happening at different sections of the code. Another nice thing about POD and CPAN is that you get a very nice visual display of your comments : http://search.cpan.org/dist/WordNet-Similarity/lib/WordNet/Similarity/PathFinder.pm (Doesn't that look lovely? All because of POD :) You can usually use perldoc to find out more about common perl modules.... perldoc cpan perldoc Data::Dumper And in fact, perldoc itself is documented using perldoc in this same style... perldoc perldoc And so is perl :) perldoc perl So, use perldoc. :) It's part of what makes Perl an appealing and portable language, and helps make our code easy for others to use and understand. BTW, perldoc doesn't replace inline comments in your code - you still need those - but, perldoc will tell someone what your program does, how to use it, what problems it might have, who wrote it, what the license is, etc. etc. which is all very useful indeed. Enjoy, Ted -- Ted Pedersen http://www.d.umn.edu/~tpederse
