gecko-dev/webtools/PLIF/STYLEGUIDE

140 lines
3.9 KiB
Plaintext

Coding Style for PLIF
---------------------
This style guide is designed to make sure that the code is consistent
throughout. It isn't necessarily the best way of writing Perl, but it
is consistent. Consistency is more important than using your preferred
method. Please follow the style guide.
Note: Exceptions will be accepted if they improve performance, but
only if they are well commented.
1. Brackets are preferred to other punctuation
return ($a eq 'a' or $b); # preferred
return $a eq 'a' || $b;
2. Use brackets around all function arguments
push(@list, $item); # preferred
push @list, $item;
foreach $item (sort(keys(%{$self->list}))) { } # preferred
foreach $item (sort keys %{$self->list}) { }
3. When calling a method for its side-effect, always use brackets
$self->go(); # preferred
$self->go;
4. When calling a method as if it was a property, omit brackets
return $self->name; # preferred;
return $self->name();
5. Don't use print(), use dump()
$self->dump(9, "foo called with bar $bar"); # preferred
print("foo called with bar $bar\n");
6. To set a property, use the method call notation
$self->name('foo'); # preferred
$self->{'name'} = 'foo';
7. method and property names should start lowercase and have a capital
letter for each word
sub myLovelyMethod { ... } # preferred
sub MyLovelyMethod { ... } # bad (first letter not lowercase)
sub mylovelymethod { ... } # bad (intervening words not capitalized)
sub my_lovely_method { ... } # bad (underscores)
8. methods should start with setting $self and taking their arguments
sub myLovelyMethod {
my $self = shift;
my($argument) = @_;
# code...
}
9. Curly brackets should cuddle
if ($condition) {
# do something
} else {
# do something else
}
10. Comments should be indented just like code
if ($condition) {
# preferred
} else {
# bad
}
11. Avoid using the implicit $_ variable
foreach my $item (@list) { $item++; } # preferred
foreach (@list) { $_++; }
12. Thou shalt avoid using useful functions (which break Win32):
alarm, chroot, crypt, endgrent, endhostent, endnetent,
endprotoent, endpwent, endservent, fork, getgrent, getgrgid,
getgrnam, getnetbyaddr, getnetbyname, getnetent, getpgrp,
getppid, getpriority, getprotoent, getpwent, getpwnam, getpwuid,
getservent, link, msgctl, msgget, msgrcv, msgsnd, semctl, semget,
semop, setgrent, sethostent, setnetent, setpgrp, setpriority,
setprotoent, setpwent, setservent, shmctl, shmget, shmread,
shmwrite, socketpair, symlink, syscall
http://ftp.univie.ac.at/packages/perl/ports/nt/FAQ/perlwin32faq5.html
13. When creating a new dependency, make sure you mark it with the
magic string 'DEPENDENCY', as in:
sub init {
my $self = shift;
my($app) = @_;
$self->SUPER::init(@_);
require Some::Module; import Some::Module; # DEPENDENCY
}
This allows for an easy listing of each dependency using 'find'
and 'grep'. Note also the way that dependencies are generally
imported inside service constructors and imported using 'require'
and 'import' instead of 'use'. This is to make sure that the
overhead of importing the relevant code is not hit unless the
module is used. Please make sure that 'import' doesn't end up
being called more than once, of course.
14. The order for declaring methods should be something along the
lines of first class methods, then the constructor (in PLIF this
is 'init'), then the methods you are overriding, then the new
methods, then the destructor ('DESTROY'). This isn't cast in stone
though. Whatever works best.
Further notes:
You'll notice PLIF doesn't use prototypes. This is because Perl
doesn't support prototypes for method calls.
- end -