I help maintain a lot of code, so this is my preference, for what it's worth (code style is basically a flamewar kind of topic; I don't really care if anyone follows what I prefer, I usually follow the existing style and don't add extraneous diffs by editing things to fit my style).
After use strict and warnings, I prefer all CPAN modules in ABC order, followed by all internal (company) modules in ABC order. Sometimes a module must be loaded before another one, in which case do that and comment why the order is unusual.
I prefer not to have superfluous comments like
# modules here
...
# globals here
...
or
###########################################
# Class Methods
...
as these should be obvious. (To me, these comments just take up vertical space.)
After that'd I prefer any global variables, including constants (even if use constant is used). Any "runtime" code follows that (populating a hash dynamically, for example), followed by methods (subs). Non-API methods or functions should be preceded by an underscore, IMHO.
Runtime code shouldn't be interspersed with (compile-time) methods, though there are naturally exceptions. For example, I've found it's convenient to put BEGIN { memoize 'method' } after subs when you use Memoize. It's also occasionally though rarely necessary to wrap a lexical (or BEGIN) block around a method (or group of methods), for example for (closured) cache variables; but cache variables might as well be global ones at the top, with a note that that's what they are (you could argue for limiting them lexically to the methods where they're used, but it clutters things and adds indentation, not to mention the "surprise" of runtime code in the middle of the module).
After all code, end with a 1;, nothing cute, followed by __END__ and POD (hopefully).
For scripts, it's pretty much the same. Try to lexically scope variables as much as possible; some globals are fine, but being sloppy with them is not only harder to maintain but also invites wasting RAM. I also prefer logical units of code to be in subs, not just a long string of stream-of-thought code. I used to put everything like
main();
exit;
sub main {
sub1();
....
}
but I found that naming the sub "main" is a potential problem (extremely rarely, to the point of pedantry - but it's because the default package of Perl is called "main"), so anymore I call it something else. Sometimes I just put a lexical block around the runtime code, maybe even label the block with "MAIN:", but I'm not really sure what's best there. I still follow this runtime block by exit;, then follow that by only non-runtime subroutines as for modules above.
I know some people prefer putting script code in modules, then basically just having something like this:
use My::App;
My::App->run();
but as someone who maintains a lot of code, I find this kind of script a bit annoying. (I think of it as "decoy" code, since where you see the error/warning will not actually be where the problem is.) I understand the desire for reusable code, but I don't know if I've ever seen the structure/logic of a script re-used anywhere. Ok, command-line parsing. I can still find it annoying, can't I? :)
For what it's worth. :) |