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