Come for the quick hacks, stay for the epiphanies. | |
PerlMonks |
Re: [RFC] Review of module code and PODby kcott (Archbishop) |
on Apr 01, 2021 at 02:58 UTC ( [id://11130656]=note: print w/replies, xml ) | Need Help?? |
G'day Bod, As far as I can see, there's nothing horribly wrong with what you've presented; however, there are a number of things I would have done differently. The following is very much biased towards my own preferences: pick and choose any bits you like; skip the bits you don't want; feel free to ignore all of it. I've also added some useful POD-related documentation links. I write a lot of modules. The majority would be for $work; although, I do write quite a few for personal use. Regardless, these are not for CPAN: the $work ones are Commercial in Confidence; the personal ones are too specific to my needs, or in some cases just testing ideas, and are not considered to be of general usefulness. Having said that, I still write these modules as if they were going to be uploaded to CPAN, and include: POD with the code; standard files such as Makefile.PL, MANIFEST, README and Changes; tests in a t/ directory; and so on. This allows me to, amongst other things: test changes (make test); easily install the modules (make install); create distributions (make dist) which I can transfer to other machines (e.g. scp to $work). I also find the POD to be exceptionally useful: six months or so after completing a module, I can rarely remember the exact details of every function and method, particularly when it comes to optional arguments and complex return values (e.g. array and hash references) — perldoc ModuleName makes my life so much easier. I never sit down and write all the files needed for the type of module described above; instead I use Module::Starter with the Module::Starter::PBP plugin. The latter is mainly for the excellent templates and does not represent a slavish adherence to "Perl Best Practices" guidelines. I have multiple config* files for my various uses. As an example, here's the currently active one for personal modules using Perl v5.32:
I have modified the templates for my own preferences. For personal modules, that can be pretty much whatever I want. For $work modules, there are certain constraints, policies, and so on, that I need to take into account (e.g. specific Perl version, copyright text, etc.). There are three test files that I always add to the templates. These use Test::Pod, Test::Pod::Coverage and ExtUtils::Manifest. The idea behind all of this is to create templates once, then let module-starter create as many module frameworks as I want, all with the same, consistent look and feel. Obviously, I still need to fill in details, such as the description of functions, but all of the boilerplate has been done for me and I can pretty much forget about that part of the process. Partly DRY; mostly "the first great virtue of a programmer": laziness. Here's the POD documentation to which I alluded earlier:
Things I would have done differently (in no particular order) and bear in mind, as I said above, these are my personal preferences:
— Ken
In Section
Meditations
|
|