Download - Best practices naming conventions
Best PracticesNaming Conventions
Mariano Wahlmann
Greatly inspired in the contents of...
&
ISBN-13: 978-0131655492ISBN-13: 978-0596001735
● Software Engineers spend most of their time reading code NOT writing it!
● Code is the only complete, accurate and updated documentation
● Easy to read code has fewer bugs
“Always code as if the person who will maintain your code is a maniac serial killer that knows where you live”
sub attr { $_ = (caller(0))[3];
s/.*\://; @_ > 1 ? $_[0]->{$_} = $_[1] : $_[0]->{$_}}
sub attr { my $self = shift; $self->{attr} = shift if(@_ ); return $self->{attr};}
vs
Namespaces
namespace → Noun [ :: Adjective ]*
package XML::Simple;
package Car::Electric;
Package Devel::NYTProf;
package Moose;
Good
Badpackage Hotel::Inventory::HotelInventory;
package Big::House;
Package Rich::People;
package Html::tag;
Begin package's names with an uppercase, if compound words are used each word must be capitalized, also when using acronyms each letter must be capitalized
Guideline
package Plane::Jet;
package Dog::Beagle;
Package XML::LibXML;
package Gtk2;
Good
Badpackage XML::SAXServiceParser;
package People::CachedList;
Package Moose::People;
package HTTP::LWPAgent;
Avoid names that relate to implementation details, there might be special cases where you don't want to do that such as packages that provide bindings to an specific library
Guideline
Subroutines or Methods
$list->is_empty;
sub calculate_net_rate {
sub get_record {
sub build_profile_using {
Good
Bad$date->ok;
sub end_tag {
$file->backup;
sub using {
routine ➝ imperative_verb [ _ adjective ]? _ noun _ preposition | imperative_verb [ _ adjective ]? _ noun _ participle | imperative_verb [ _ adjective ]? _ noun
Guideline
Pick function and method names that describe what they do and not how they do it
$element->is_valid;
$node->has_children;
$hotel->room_available_for(@dates);
$list->contains($element);
Good
Bad$date->valid;
$record->bad_record;
$list->list_empty;
$process->running;
Begin subroutine or method names with is_ or has_ if they return a boolean, there might be special cases where you don't want to do that
Guideline
sub internal_method {
sub private_function {
$self->_build_list;
$self->_calculate_price;
$self->_store($element);
$self->_initialize(@_);
Good
Prefix “internal use only” subroutines or “Private” methods with an underscore
Guideline
Bad
$car->engine;
$face->mouth;
$list->next_item;
$person->name;
Good
Bad$car->get_engine;
$list->item;
$plane->retrieve_model;
$dog->leg;
Use nouns for subroutines or methods which return a specific object or value
Guideline
$car->start_engine;
$face->smile;
$list->remove_all;
$person->clone;
Good
Bad$car->engine;
$face->happy;
$list->clear;
$person->new_instance;
Use imperative for subroutines or methods that performs an action
Guideline
Variables
my $name = 'Doe';
my $first_name = 'John';
my $total_price = $net_rate + $taxes
my $next_node;
Good
Badmy $name_first;
my $name_last;
my $node;
my $sum;
Variable ➝ [ adjective _ ]* nounGuideline
Use lowercase for variables and if compound words are use separate each word with underscore
my @errors;
my %author_of;
my @brands;
my %config;
Good
Badmy @record;
my %authors;
my %places;
my @user;
Name arrays in plural and hashes in singular
Guideline
my @sales_for;
print “$sales_for[$month]\n”;
my %title_of;
print “$title_of{$book}\n”;
Good
Badmy @sales;
print “$sales[$index]\n”;
my %titles;
print “$titles{$isbn}\n”;
lookup_variable ➝ [ adjective _ ]* noun _ preposition
Guideline
Adding a preposition to the end of lookup variables make names more readable
Common
my $io_stream;
my $tcp_sock;
my $udp_socket;
sub gmt_timestamp {
Good
Badmy $left;
my $tcp_st;
my @e;
sub g_tmstmp {
Avoid ambiguous abbreviations or names, is preferable to use short full names. If you have to abbreviate use well-accepted abbreviations
Guideline
use constant PI => 3.14;
my $area = PI * $radius**2 ;
use constant BASE_URL => 'http://a.com';
my $home_url = “${\BASE_URL}/home”;
Good
Badmy $area = 3.14 * $radius**2;
my $base_url = 'http://a.com';
my $home_url = 'http://a.com/home';
if ( $#results < 50 ) {
Use named constants, using the constant pragma. For named constants use uppercase
Guideline
Thank You!
Source: http://xkcd.org