mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-11-02 15:15:23 +00:00
140 lines
3.9 KiB
Plaintext
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 -
|