import rt 3.6.6

[freeside.git] / rt / lib / RT / StyleGuide.pod

diff --git a/rt/lib/RT/StyleGuide.pod b/rt/lib/RT/StyleGuide.pod
index 4a45e82..ff9a1b5 100644 (file)
--- a/rt/lib/RT/StyleGuide.pod
+++ b/rt/lib/RT/StyleGuide.pod
@@ -40,10 +40,8 @@ We hope to add any significant changes at the bottom of the document.
 
 =head2 Perl Version
 
-We code everything to perl 5.6.1. Some features require advanced unicode
-features in perl 5.8.0. It is acceptable that unicode features work only for 
-US-ASCII on perl 5.6.1. 
-
+We code everything to perl 5.8.3 or higher.  Complete unicode support
+requires bugfixes found in 5.8.3.
 
 =head2 Documentation
 
@@ -239,7 +237,27 @@ leads to cleaner code.
         my $var1 = shift;                       # right
         my $var2 = shift;                       
 
+=head2 Method parameters
+
+If a method takes exactly one mandatory argument, the argument should be
+passed in a straightforward manner:
+
+        my $self = shift;
+        my $id = shift;
+
+In all other cases, the method needs to take named parameters, usually
+using a C<%args> hash to store them:
 
+        my $self = shift;
+        my %args = ( Name => undef,
+                     Description => undef,
+                     @_ );
+
+You may specify defaults to those named parameters instead of using
+C<undef> above, as long as it is documented as such.
+
+It is worth noting that the existing RT codebase had not followed this
+style perfectly; we are trying to fix it without breaking exsiting APIs.
 
 =head2 Tests
 
@@ -857,7 +875,28 @@ is a good chance it will not be dealt with.
 Send patches to rt-<major-version>-bugs@fsck.com, too.  Use C<diff
 -u> for patches.
 
+=head1 SCHEMA DESIGN
+
+RT uses a convention to denote the foreign key status in its tables.
+The rule of thumb is:
+
+=over 4
+
+=item When it references to another table, always use the table name
+
+For example, the C<Template> field in the C<Scrips> table refers to
+the C<Id> of the same-named C<Template> table.
+
+=item Otherwise, always use the C<Id> suffix
+
+For example, the C<ObjectId> field in the C<ACL> table can refer
+to any object, so it has the C<Id> suffix.
+
+=back
 
+There are some legacy fields that did not follow this rule, namely
+C<ACL.PrincipalId>, C<GroupMembers.GroupId> and C<Attachments.TransactionId>,
+but new tables are expected to be consistent.
 
 =head1 TO DO