# from Ricardo SIGNES
# on Monday 09 April 2007 05:10 am:
>I need to finish/test/release my PC subclass that looks at
>@PKG::POD_COVERAGE_TRUSTME.
I saw that in rt, but I really think pod is the place for it. Why
clutter the code with variables which are only used by a tool that
reads pod? Isn't that what '=for' is for?
>I am definitely not happy with the idea
> of letting Pod::Coverage just look for subs declared with "sub name"
> as you suggest. I generate too many methods dynamically.
Well, we could have *that* debate, but I'm inclined to think that a
project should get to choose between them (at least in terms of what's
the policy for whether the code is ship-ready.) I'm firmly on the
"human decisions supported by tools" side of the fence.
We don't really have the option to generate pod dynamically (at least,
not outside of the build system), so I tend to document the
autogenerated methods as:
=head2 menu_view_tab_<foo>
Activates the <foo> sidebar tab.
=cut
And I might include every method in that bit of documentation, but I'm
not going to =head2 or even =item them.
With a symbol-table walking scheme, I now have to add an explicit or
regexp list of trustme's to match that. With a static scan, I don't
have to do anything.
What was bugging me about the symtable walk was stuff like:
# override this because the default behavior makes no sense
sub SetFocus {shift->focus_current(@_);}
In My Policy, that doesn't belong in the pod documentation because it is
an implementation detail. It might get a mention in the focus_current
pod, but again, will not get an =head[2-4] or =item. Being able to say
"trust me" with a leading space or semicolon seems like a rather useful
convention.
Of course, there's also "the code can not be loaded" (e.g. on this
computer - whether lack of prereqs, failure to be linux, etc.) I guess
failure to die when eval("require $package") fails is a bug? ATM,
Test::Pod::Coverage says "ok" there, but I'm not sure who's bug it is.
Shouldn't that at least be a "skipped: $module failed to load"?
The pod is static, so with all of the problems of compiling the code,
plus the speed difference, it seems like this is one case where
simplistic static code scanning is a net win for some. Just like
kwalitee, it is not a perfect metric, but I think it makes a good tool.
Symbol Table Walk:
* picks-up on magic subs (iff the magic is in your package.)
(skips accessors, constants, etc.)
* requires explicit trustme/private declarations
* requires that the code compiles on the current machine/platform
* is slow
Static Code Scanning:
* only sees statically declared subs
* ignores anything which doesn't m/^sub [A-Za-z]\w+/
(sort of a 'defaults to "trustme"' style)
* is unaffected by dependency/platform issues
* is quick
Which of those items are pros or cons mostly depends on your POV. It
seems like there's a good case for one or the other in given
situations. I might use the STW as an occasional audit, but have the
SCS as the check on the nightly build. I tend to have my eyes on the
code enough to see blatant violations, so I'm looking to catch errors
which look correct such as:
=head2 foo_bar_bat
Does the bar to foo's baz.
=cut
sub foo_bar_baz {
...
What perplexes me is I guess: why have we only had the one scheme for so
long? I caught a couple of actual mis-documented bits (such as above)
with the SCS, but the STW always made so much noise that I had
basically just given up on making it work until yesterday. I wonder
how many others have similarly thrown up their hands and just walked
away from pod coverage because of that?
In my case, the SCS is much more pragmatic in that it allows me to catch
honest errors, whereas the STW punishes my tendency to not repeat
myself, plus takes longer *and* misses checking all of the
windows-specific code.
--Eric
--
"Unthinking respect for authority is the greatest enemy of truth."
--Albert Einstein
---------------------------------------------------
http://scratchcomputing.com
---------------------------------------------------
