Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl Monk, Perl Meditation
 
PerlMonks  

Re^3: RFC: Any and all comments welcome on style/technique in new module to calculate G statistic (rather)

by hilitai (Monk)
on Jul 30, 2007 at 13:17 UTC ( #629551=note: print w/replies, xml ) Need Help??


in reply to Re^2: RFC: Any and all comments welcome on style/technique in new module to calculate G statistic (rather)
in thread RFC: Any and all comments welcome on style/technique in new module to calculate G statistic

I noticed the problem with the intermixed POD as soon as I put it in the PerlMonks text box. It's very easy to distinguish POD when you're looking at it with a syntax-highlighting text editor, but in plain black and white, it's much more difficult. This is a drawback to POD I hadn't thought about before, which is too bad, because I find keeping the documentation with the method/function to be very handy. Javadoc commenting gets around this problem by putting comment chars. on every line of the documentation comment; it's a pity that POD doesn't do the same. At least, I can't think of any non-cumbersome way to do this.

Well, now I know why just about everybody else puts their POD at the beginning or end of the module.

Thanks for the comments re: open(). Now that I think about it, the module should handle data passed in as arrayrefs. as well as text files; I'll have to think about this a little more. (And yes, top-level "Gstat::" won't fly.)

  • Comment on Re^3: RFC: Any and all comments welcome on style/technique in new module to calculate G statistic (rather)

Replies are listed 'Best First'.
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

    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.

    --
    print "Just Another Perl Adept\n";

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://629551]
help
Chatterbox?
and all is quiet...

How do I use this? | Other CB clients
Other Users?
Others lurking in the Monastery: (5)
As of 2018-06-19 05:27 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    Should cpanminus be part of the standard Perl release?



    Results (111 votes). Check out past polls.

    Notices?