On Fri, Aug 04, 2000 at 03:21:37AM -0800, Michael Fowler wrote:
>On Fri, Aug 04, 2000 at 10:37:02AM +0100, Leon Brocard wrote:
>> Michael Fowler sent the following bits through the ether:
>>
>> > Personally, I think FindBin is a bit of a sore thumb. Its name, the
>> > capitalization of its variable names
>>
>> I suppose we could try and define some Perl Naming Conventions - ie
>> instead of DumpCore() we should have dump_core(). This'll really annoy
>> Java programmers. Other ideas needed though...
>
>I think no matter what is decided, consistency-wise, someone is going to be
>unhappy with it. If we use DumpCore() the C programmers won't like us,
>dump_core() and the C++ and Java programmers will throw fits. I think the
>best thing we can do is decide on what -Perl- programmers want.
>Unfortunately, this is rather difficult to pin down, but we should probably
>take hints from the language itself.
man perlstyle?
o While short identifiers like $gotit are probably ok,
use underscores to separate words. It is generally
easier to read $var_names_like_this than
$VarNamesLikeThis, especially for non-native speakers
of English. It's also a simple rule that works
consistently with VAR_NAMES_LIKE_THIS.
Package names are sometimes an exception to this rule.
Perl informally reserves lowercase module names for
"pragma" modules like integer and strict. Other
modules should begin with a capital letter and use
mixed case, but probably without underscores due to
limitations in primitive file systems' representations
of module names as files that must fit into a few
sparse bytes.
o You may find it helpful to use letter case to indicate
the scope or nature of a variable. For example:
$ALL_CAPS_HERE constants only (beware clashes with perl vars!)
$Some_Caps_Here package-wide global/static
$no_caps_here function scope my() or local() variables
Function and method names seem to work best as all
lowercase. E.g., $obj->as_string().
You can use a leading underscore to indicate that a
variable or function should not be used outside the
package that defined it.
That seems relatively clear to me.
I should probably distil Netizen's internal naming wisdom into a set of
guidelines, sometime.
Oh, what the hell, now's as good as any other time:
* Variables are things are nouns. Give them noun names.
$name, $total, $input
* Plural variables should have plural names
@employees, @items, %contact_details
* Hash names should be written so that looking up an element reads clearly:
$email_address{Skud} reads as "the email address of Skud"
* Hashes with scalars as values should have singular names:
my $address = $email_address{Skud};
* Hashes with arrayrefs or hashrefs as values should have plural names:
my @addresses = @{$email_addresses{Skud}};
* Subroutines and methods are verbs. Give them verb names.
GOOD: print_address(), get_address()
BAD: address()
* Putting "do" on the start of a subroutine name is almost always pointless
* The length of the name of something should be proportional to its scope.
* Never abbreviate at the expense of clarity
* Never confuse verbosity for clarity
* If you can't find the perfect name for something, use a thesaurus. Don't
settle for a second-rate name. It may take a day or three to find it,
but it's worth the wait.
* If you have sets of things in your code, make sure your names are
consistent:
GOOD: employee_name, employee_phone, employee_address
BAD: employee_name, phone, emp_address
* If you're basing your naming scheme on an existing domain of knowledge
or on a metaphor, be consistent:
GOOD: rm, mv, cp
BAD: rm, mv, copy
GOOD: desktop, folder, trashcan
BAD: desktop, directory_name, deleted_files
* If you can't read Perl code out loud and feel that it makes sense, your
names are probably wrong.
I think that's probably most of it. Really should write them up more
completely and stick them on a website someplace.
K.
--
Kirrily Robert -- <[EMAIL PROTECTED]> -- http://netizen.com.au/
Open Source development, consulting and solutions
Level 10, 500 Collins St, Melbourne VIC 3000
Phone: +61 3 9614 0949 Fax: +61 3 9614 0948 Mobile: +61 410 664 994
