Beefy Boxes and Bandwidth Generously Provided by pair Networks
go ahead... be a heretic
 
PerlMonks  

Campaign to clean up CPAN modules' POD?

by cLive ;-) (Prior)
on May 21, 2007 at 18:39 UTC ( #616621=perlmeditation: print w/replies, xml ) Need Help??

I've been browsing a bunch of modules lately, and can't help but see that many of them don't follow "best practices" (heh, not that I always do either :)

But, at the very least, shouldn't they be using strict, warnings and lexically scoped variables. CGI and GD are prime examples (CGI appears to haphazardly use my and -w though).

Since module documentation is where a lot of people first learn how to code, shouldn't we be politely asking module owners to update their documentation to provide at least the basics of good practice?

Or am I opening a can of worms that should be kept shut? ;-)

  • Comment on Campaign to clean up CPAN modules' POD?

Replies are listed 'Best First'.
Re: Campaign to clean up CPAN modules' POD?
by stvn (Monsignor) on May 21, 2007 at 19:56 UTC
    Since module documentation is where a lot of people first learn how to code, shouldn't we be politely asking module owners to update their documentation to provide at least the basics of good practice?

    I have a better idea, send those module owners a patch instead.

    You could get involved in the Phalanx project, this is a great way to help improve overall CPAN quality.

    -stvn
      Thanks for the link - I hadn't heard of this project. Interesting...
Re: Campaign to clean up CPAN modules' POD?
by ysth (Canon) on May 22, 2007 at 02:15 UTC
    If the question is, should snippets of code in module POD always use strict, warnings, and lexicals, my answer is an emphatic no. They shouldn't include anything that distracts from the example they are trying to provide. (Though in most cases, using lexicals isn't what I'd call a distraction.)
Re: Campaign to clean up CPAN modules' POD?
by rinceWind (Monsignor) on May 22, 2007 at 13:22 UTC

    When it comes to documentation improvement, there's annocpan. I'd recommend signing up for an account and getting stuck in, suggesting changes. Of course, it's up to the module author whether they take your suggestions on board.

    --
    wetware hacker
    (Qualified NLP Practitioner and Hypnotherapist)

Re: Campaign to clean up CPAN modules' POD?
by educated_foo (Vicar) on May 21, 2007 at 20:01 UTC
    Dear God no. Trying to advocate your coding standards in other people's code is silly enough; doing so in their documentation is somewhere between useless and counterproductive.

    Please keep the can shut. There's no need to run around trying to stamp out thought-crime.

      Which is why I would keep it to just:

      • use strict
      • use warnings (or -w)
      • lexically scope variables

      None of those are particularly controversial. I'm not arguing about "cuddled elses", "$$ v. $->" dereferencing etc... tempting though it is :)

      I just hate walking in on someone's code where they've pretty much copied the example verbatim and not thought about tidying it up. I'd rather hit such code with strict and warnings in place if it's something I now have to deal with.

        I just hate walking in on someone's code where they've pretty much copied the example verbatim and not thought about tidying it up.

        If they haven't thought there, they didn't think elsewhere either. Verbatim copies of pod examples are a easy to find red flag. You wouldn't improve their overall code quality had you examples for every one of their needs in any pod ...

        --shmem

        _($_=" "x(1<<5)."?\n".q·/)Oo.  G°\        /
                                      /\_¯/(q    /
        ----------------------------  \__(m.====·.(_("always off the crowd"))."·
        ");sub _{s./.($e="'Itrs `mnsgdq Gdbj O`qkdq")=~y/"-y/#-z/;$e.e && print}
      A reply falls below the community's threshold of quality. You may see it by logging in.
Re: Campaign to clean up CPAN modules' POD?
by leocharre (Priest) on May 22, 2007 at 11:59 UTC

    I have beef with some pod on cpan. I've been really hurting using some modules off and on because of horrible documentation. Not so much because of poor examples, but because of 'no' examples- or .. just a lot of stuff missing.

    I've felt like sending a please please or a note.. But then I realize, these monkeys are just like me- they're busy as all hell- and I should be glad they put something out there and documented it. So the rare time I do ask or suggest- I do it with the most care and respect possible (it's appreciated)- Other then that- The solution is to write pod yourself!!!

    I don't mean to come accross pushy- What I am thinking of is write an addon tutorial to some module you think is poorly documented. I sure should put the keyboard where my mouth is and do that myself. Thanks for bringing all this up.

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: perlmeditation [id://616621]
Approved by kyle
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others contemplating the Monastery: (5)
As of 2022-05-26 14:43 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    Do you prefer to work remotely?



    Results (93 votes). Check out past polls.

    Notices?