On Mon, Aug 18, 2003 at 09:43:34AM -0400, Potozniak, Andrew wrote: > Since we're on the topic of scrutinizing CPAN distributions I would like to > contribute something that I do not like in some of the distributions that I > have come across. I don't know if it has been brought up on this thread yet > but here it goes: > > 1) I do not like in-module POD as it is hard to tell the difference > between code and pod when you are scrolling throught the module. I > personally think POD should go at the end and comments should be added > in-module and definetly before sub routines. > > 2) I found that commenting blocks of code with what it does in a > general sense is good when users want to know what something does, namely a > subrountine. I think it is beneficial to have "black box" commenting for > your subroutines and then commenting in line to further describe the code > that you wrote.
Personal and asthetic style nits cannot be part of any code analysis that claims to be non-partisan or even wishes to exist. It will make the analysis worthless since nobody will agree on what you feel is "good" style. Stick to choices that don't rely on asthetics. Consider that the very style you hold up as bad in #1 many people find very good and actually teach (I'm one of them). Ironicly, the style you don't like in #1 is the very style you promote in #2. Replace '"black box" commenting' with POD documentation and you have in-module POD. Plus the benefits of not duplicating your documentation of the module in the comments and the POD docs. I guess your beef is there's no visually distinctive line of # running down the left side of the screen to distinguish it from the code when you use POD. Might I suggest a good syntax highlighting editor? -- Michael G Schwern [EMAIL PROTECTED] http://www.pobox.com/~schwern/ The key, my friend, is hash browns. http://www.goats.com/archive/980402.html
