work in progress

git-svn-id: svn://10.0.0.236/trunk@94031 18797224-902f-48f8-a5cc-f745e15eee43

mozilla/webtools/PLIF/STYLEGUIDE

@@ -0,0 +1,127 @@
+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:
+
+     package PLIF::Coses;
+     use strict;
+     use vars qw(@ISA);
+     use PLIF::Service;
+     use XML::Parser; # DEPENDENCY
+     @ISA = qw(PLIF::Service);
+     1;
+
+    This allows for an easy listing of each dependency using 'find'
+    and 'grep'.
+
+
+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.