Come for the quick hacks, stay for the epiphanies. | |
PerlMonks |
Re^4: RFC: Any and all comments welcome on style/technique in new module to calculate G statistic (rather)by vrk (Chaplain) |
on Jul 31, 2007 at 09:53 UTC ( [id://629775]=note: print w/replies, xml ) | Need Help?? |
Personally, I advocate and use the same documentation style as you use in this module. I don't know how common it is either, but the greatest advantage is that documentation and code are in the same place. If the interface or the pre- or postconditions change in the code, it is easy to update them in the documentation: the documentation is just over there, hard to miss. (Here's one gripe: document your internal methods, too. Put them under =head1 INTERNAL FUNCTIONS or somesuch, then use podselect to remove them from the official documentation, if it matters.)True, without syntax highlighting it's harder to make a visual difference between code and documentation, but I don't think this is a big issue. Your eye will get used to noticing the "code sections" between =cut and =head[12] and "documentation sections" between =head[12] and =cut. It's not ideal, but it's the best I have found.
--
In Section
Meditations
|
|