This commit was generated by cvs2svn to compensate for changes in r4407,

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

diff --git a/rt/lib/RT/StyleGuide.pod b/rt/lib/RT/StyleGuide.pod
index 95b2e3a..f0d1d15 100644 (file)
--- a/rt/lib/RT/StyleGuide.pod
+++ b/rt/lib/RT/StyleGuide.pod
@@ -239,7 +239,27 @@ leads to cleaner code.
         my $var1 = shift;                       # right
         my $var2 = shift;                       
 
         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
 
 
 =head2 Tests
 


@@ -804,11 +824,9 @@ It is important not to localize  the names of rights or statuses within RT's cor
 
 This is for new programs, modules, specific APIs, or anything else.
 
 
 This is for new programs, modules, specific APIs, or anything else.
 

-Contact for core team is the slashcode-development mailing list.
-

 =over 4
 
 =over 4
 

-=item Present idea to core team
+=item Present idea to rt-devel

 
 We may know of a better way to approach the problem, or know of an
 existing way to deal with it, or know someone else is working on it. 
 
 We may know of a better way to approach the problem, or know of an
 existing way to deal with it, or know someone else is working on it. 


@@ -816,9 +834,9 @@ This is mostly informal, but a fairly complete explanation for the need
 and use of the code should be provided.
 
 
 and use of the code should be provided.
 
 

-=item Present complete specs to core team
+=item Present complete specs to rt-devel

 
 

-The complete proposed API to the core team should be submitted for
+The complete proposed API  should be submitted for

 approval and discussion.  For web and command-line programs, present the
 functionality and interface (op codes, command-lin switches, etc.).
 
 approval and discussion.  For web and command-line programs, present the
 functionality and interface (op codes, command-lin switches, etc.).
 


@@ -827,13 +845,8 @@ boilerplate and fill it in.  You can make changes later if necessary,
 but fill it in as much as you can.
 
 
 but fill it in as much as you can.
 
 

-=item Announce any changes to interface
-
-If the way it works or how it is called is going to change, notify the core
-team.

 
 

-
-=item Prepare for core review
+=item Prepare for code review

 
 When you are done, the code will undergo a code review by a member of
 the core team, or someone picked by the core team.  This is not to
 
 When you are done, the code will undergo a code review by a member of
 the core team, or someone picked by the core team.  This is not to


@@ -843,9 +856,6 @@ break other code, that it follows the documentation and existing
 proposal.  It is to check for possible optimizations or better ways of
 doing it.
 
 proposal.  It is to check for possible optimizations or better ways of
 doing it.
 

-For members of the core team, one or more other members of the team will
-perform the review.
-

 Note that all code is expected to follow the coding principles and style
 guide contained in this document.
 
 Note that all code is expected to follow the coding principles and style
 guide contained in this document.
 


@@ -867,7 +877,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.
 
 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
 
 
 =head1 TO DO