gecko-dev/webtools/PLIF/STYLEGUIDE

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 -