develooper Front page | perl.perl6.stdlib | Postings from August 2000

Re: Define consistent and standard

From:
skud
Date:
August 5, 2000 08:13
Subject:
Re: Define consistent and standard
Message ID:
20000806011322.E8485@netizen.com.au
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 -- <skud@netizen.com.au> -- 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



nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About