Re: RFC: Any and all comments welcome on style/technique in new module to calculate G statistic

[liverpole]

Hi hilitai,

Your module is very readable; nice job!

I particularly like your use of pod, intermixed with the code in such a way that each subroutine is documented by the corresponding pod block.  (It may be a more common technique than I'm aware, but I haven't seen it before).

Here are a couple of minor suggestions, all related to open:

1. You might consider using lexically-scoped filehandles, via FileHandle or IO::File.  Using IN runs the risk of stomping on a globally-defined IN from somewhere else (eg. the calling program).  (Same with EXP).
2. You don't need quotation marks around $basefile in open(IN, "$basefile").  (Same with $expFile).
3. Why not use the 3-argument form of open?

[tye]

Using IN runs the risk of stomping on a globally-defined IN from somewhere else (eg. the calling program).

Only if the calling program does something stupid like:

open( Gstat::IN, ...

I particularly like your use of pod, intermixed with the code in such a way that each subroutine is documented by the corresponding pod block.

While that works for strictly linear reading of code, the lack of visual distictiveness of POD (especially when POD includes code snippets, which most good POD does) make that style problematic for many other styles of reading code. It isn't all that bad in this particular case but that is mostly due to the fact that the pod for most of the functions is nearly minimal. When the documentation becomes more extensive (which usually happens with good modules), it will become quite painful to find the code amid the POD, at least for people like me who usually read code more holistically than strictly linearly. I also find that it interferes with updating and especially organizing the POD.

Why not use the 3-argument form of open?

Or, if you don't want to make your code not work for people who for some reason may be stuck with an old version of Perl, at least be specific about the fact that you want to read the files (which provides the most important benefits of 3-argument open):

open( EXP, "< $expFile"­ )

Not that I disagree with any of your suggestions (just with your encouragement of intermixing POD and code).

[hilitai]

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.)

[vrk]

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.