Master to 4.2.8
[usit-rt.git] / lib / RT / StyleGuide.pod
1 =head1 NAME
2
3 RT::StyleGuide - RT Style Guide
4
5 =head1 CAVEATS
6
7 This file is somewhat out of date; L<hacking> takes precedence over it.
8
9 =head1 INTRODUCTION
10
11 All code and documentation that is submitted to be included in the RT
12 distribution should follow the style in this document.  This is not to
13 try to stifle your creativity, but to make life easier for everybody who
14 has to work with your code, and to aid those who are not quite sure how
15 to do something.
16
17 These conventions below apply to perl modules, web programs, and
18 command-line programs, specifically, but also might apply to some
19 degree to any Perl code written for use in RT.
20
21 Note that these are all guidelines, not unbreakable rules.  If you have
22 a really good need to break one of the rules herein, however, then it is
23 best to ask on the B<rt-devel> mailing list first.
24
25 Note that with much of this document, it is not so much the Right Way as
26 it is Our Way.  We need to have conventions in order to make life easier
27 for everyone.  So don't gripe, and just follow it, because you didn't
28 get a good grade in "Plays Well With Others" in kindergarten and you
29 want to make up for it now.
30
31 If you have any questions, please ask us on the B<rt-devel> mailing list:
32
33         http://www.bestpractical.com/rt/lists.html
34
35 We don't always follow this guide.  We are making changes throughout
36 our code to be in line with it.  But just because we didn't do
37 it yet, that is no excuse.  Do it anyway.  :-)
38
39 This document is subject to change at the whims of the core RT team.
40 We hope to add any significant changes at the bottom of the document.
41
42
43 =head1 CODING PRINCIPLES
44
45 =head2 Perl Version
46
47 We code everything to Perl 5.10.1 or higher.
48
49 =head2 Documentation
50
51 All modules will be documented using the POD examples in the module
52 boilerplate.  The function, purpose, use of the module will be
53 explained, and each public API will be documented with name,
54 description, inputs, outputs, side effects, etc.
55
56 If an array or hash reference is returned, document the size of the
57 array (including what each element is, as appropriate) and name each key
58 in the hash.  For complex data structures, map out the structure as
59 appropriate (e.g., name each field returned for each column from a DB
60 call; yes, this means you shouldn't use "SELECT *", which you shouldn't
61 use anyway).
62
63 Also document what kind of data returned values are.  Is it an integer,
64 a block of HTML, a boolean?
65
66 All command-line program options will be documented using the
67 boilerplate code for command-line programs, which doesn't yet exist.
68 Each available function, switch, etc. should be documented, along
69 with a statement of function, purpose, use of the program.  Do not
70 use the same options as another program, for a different purpose.
71
72 All web templates should be documented with a statement of function,
73 purpose, and use in a mason comment block.
74
75 Any external documents, and documentation for command-line programs and
76 modules, should be written in POD, where appropriate. From there, they
77 can be translated to many formats with the various pod2* translators.
78 Read the perlpod manpage before writing any POD, because although POD is
79 not difficult, it is not what most people are used to.  It is not a
80 regular markup language; it is just a way to make easy documentation
81 for translating to other formats.  Read, and understand, the perlpod
82 manpage, and ask us or someone else who knows if you have any questions.
83
84
85 =head2 Version
86
87 Our distribution versions use tuples, where the first number is the
88 major revision, the second number is the version, and third
89 number is the subversion.  Odd-numbered versions are development
90 versions.  Examples:
91
92         1.0.0           First release of RT 1
93         1.0.1           Second release of RT 1.0
94         1.0.10          etc.
95         1.1.0           First development release of RT 1.2 (or 2.0)
96         2.0.0           First release of RT 2
97
98 Versions may end in "rc" and a number if they are release candidates:
99
100         2.0.0rc1        First release candiate for real 2.0.0
101
102
103 =head2 Comments
104
105 All code should be self-documenting as much as possible.  Only include
106 necessary comments.  Use names like "$ticket_count", so you don't need to
107 do something like:
108
109         # ticket count
110         my $tc = 0;
111
112 Include any comments that are, or might be, necessary in order for
113 someone else to understand the code.  Sometimes a simple one-line
114 comment is good to explain what the purpose of the following code is
115 for.  Sometimes each line needs to be commented because of a complex
116 algorithm.  Read Kernighan & Pike's I<Practice of Programming> about
117 commenting.  Good stuff, Maynard.
118
119
120 =head2 Warnings and Strict
121
122 All code must compile and run cleanly with "use strict" enabled and the
123 perl "-w" (warnings) option on.  If you must do something that -w or
124 strict complains about, there are workarounds, but the chances that you
125 really need to do it that way are remote.
126
127 =head2 Lexical Variables
128
129 Use only lexical variables, except for special global variables
130 ($VERSION, %ENV, @ISA, $!, etc.) or very special circumstances (see
131 %HTML::Mason::Commands::session ).  Global variables
132 for regular use are never appropriate.  When necessary, "declare"
133 globals with "use vars" or "our()".
134
135 A lexical variable is created with my().  A global variable is
136 pre-existing (if it is a special variable), or it pops into existence
137 when it is used.  local() is used to tell perl to assign a temporary
138 value to a variable.  This should only be used with special variables,
139 like $/, or in special circumstances.  If you must assign to any global
140 variable, consider whether or not you should use local().
141
142 local() may also be used on elements of arrays and hashes, though there
143 is seldom a need to do it, and you shouldn't.
144
145
146 =head2 Pass by Reference
147
148 Arrays and hashes should be passed to and from functions by reference
149 only.  Note that a list and an array are NOT the same thing.  This
150 is perfectly fine:
151
152         return($user, $form, $constants);
153
154 An exception might be a temporary array of discrete arguments:
155
156         my @return = ($user, $form);
157         push @return, $constants if $flag;
158         return @return;
159
160 Although, usually, this is better (faster, easier to read, etc.):
161
162         if ($flag) {
163                 return($user, $form, $constants);
164         } else {
165                 return($user, $form);
166         }
167
168 We need to talk about Class::ReturnValue here.
169
170
171 =head2 Method parameters
172
173 If a method takes exactly one mandatory argument, the argument should be
174 passed in a straightforward manner:
175
176         my $self = shift;
177         my $id = shift;
178
179 In all other cases, the method needs to take named parameters, usually
180 using a C<%args> hash to store them:
181
182         my $self = shift;
183         my %args = (
184             Name => undef,
185             Description => undef,
186             @_
187         );
188
189 You may specify defaults to those named parameters instead of using
190 C<undef> above, as long as it is documented as such.
191
192 It is worth noting that the existing RT codebase had not followed this
193 style perfectly; we are trying to fix it without breaking existing APIs.
194
195 =head2 Tests
196
197 Modules should provide test code, with documentation on how to use
198 it.  Test::More makes it easy to create tests. Any code you write
199 should have a testsuite.  Any code you alter should have a test
200 suite. If a patch comes in without tests, there is something wrong.
201
202 When altering code, you must run the test harness before submitting a
203 patch or committing code to the repository.
204
205 "make test" will run the test suite.
206
207 =head2 STDIN/STDOUT
208
209 Always report errors using $RT::Logger. It's a Log::Dispatch object.
210 Unlike message meant for the user, log messages are not to be
211 internationalized.
212
213 There are several different levels ($RT::Logger methods) of logging:
214
215 =over 4
216
217 =item debug
218
219 Used for messages only needed during system debugging.
220
221 =item info
222
223 Should be used to describe "system-critical" events which aren't errors.
224 Examples: creating users, deleting users, creating tickets, creating queues,
225 sending email (message id, time, recipients), recieving mail, changing
226 passwords, changing access control, superuser logins)
227
228 =item error
229
230 Used for RT-generated failures during execution.
231
232 =item crit
233
234 Should be used for messages when an action can not be completed due to some
235 error condition beyond our control.
236
237 =back
238
239 In the web UI and modules, never print directly to STDERR.  Do not print
240 directly to STDOUT, unless you need to print directly to the user's console.
241
242 In command-line programs, feel free to print to STDERR and STDOUT as
243 needed for direct console communication. But for actual error reporting,
244 use the logging API.
245
246
247 =head2 System Calls
248
249 Always check return values from system calls, including open(),
250 close(), mkdir(), or anything else that talks directly to the system.
251 Perl built-in system calls return the error in $!; some functions in
252 modules might return an error in $@ or some other way, so read the module's
253 documentation if you don't know.  Always do something, even if it is
254 just calling $RT::Logger->warning(), when the return value is not what you'd expect.
255
256
257
258 =head1 STYLE
259
260 Much of the style section is taken from the perlsyle manpage.  We make
261 some changes to it here, but it wouldn't be a bad idea to read that
262 document, too.
263
264 =head2 Terminology
265
266 =over 4
267
268 =item function vs. sub(routine) vs. method
269
270 Just because it is the Perl Way (not necessarily right for all
271 languages, but the documented terminology in the perl documentation),
272 "method" should be used only to refer to a subroutine that are object
273 methods or class methods; that is, these are functions that are used
274 with OOP that always take either an object or a class as the first
275 argument. Regular subroutines, ones that are not object or class
276 methods, are functions.  Class methods that create and return an object
277 are optionally called constructors.
278
279 =item Users
280
281 "users" are normally users of RT, the ones hitting the site; if using
282 it in any other context, specify.
283 "system users" are user
284 names on the operating system.  "database users" are the user names in
285 the database server.  None of these needs to be capitalized.
286
287 =back
288
289
290 =head2 Names
291
292 Don't use single-character variables, except as iterator variables.
293
294 Don't use two-character variables just to spite us over the above rule.
295
296 Constants are in all caps; these are variables whose value will I<never>
297 change during the course of the program.
298
299         $Minimum = 10;          # wrong
300         $MAXIMUM = 50;          # right
301
302 Other variables are lowercase, with underscores separating the words.
303 They words used should, in general, form a noun (usually singular),
304 unless the variable is a flag used to denote some action that should be
305 taken, in which case they should be verbs (or gerunds, as appropriate)
306 describing that action.
307
308         $thisVar      = 'foo';  # wrong
309         $this_var     = 'foo';  # right
310         $work_hard    = 1;      # right, verb, boolean flag
311         $running_fast = 0;      # right, gerund, boolean flag
312
313 Arrays and hashes should be plural nouns, whether as regular arrays and
314 hashes or array and hash references.  Do not name references with "ref"
315 or the data type in the name.
316
317         @stories     = (1, 2, 3);      # right
318         $comment_ref = [4, 5, 6];      # wrong
319         $comments    = [4, 5, 6];      # right
320         $comment     = $comments->[0]; # right
321
322 Make the name descriptive.  Don't use variables like "$sc" when you
323 could call it "$story_count".  See L<"Comments">.
324
325 There are several variables in RT that are used throughout the code,
326 that you should use in your code.  Do not use these variable names for
327 anything other than how they are normally used, and do not use any
328 other variable names in their place.  Some of these are:
329
330         $self           # first named argument in object method
331
332 Subroutines (except for special cases, like AUTOLOAD and simple accessors)
333 begin with a verb, with words following to complete the action.  Accessors
334 don't start with "Get" if they're just the name of the attribute.
335
336 Accessors which return an object should end with the suffix Obj.
337
338 This section needs clarification for RT.
339
340 Words begin with a capital letter.  They
341 should as clearly as possible describe the activity to be peformed, and
342 the data to be returned.
343
344
345
346         Load();         # good
347         LoadByName();   # good
348         LoadById();             # good
349
350 Subroutines beginning with C<_> are special: they are not to be used
351 outside the current object.  There is not to be enforced by the code
352 itself, but by someone very big and very scary.
353
354 For large for() loops, do not use $_, but name the variable.
355 Do not use $_ (or assume it) except for when it is absolutely
356 clear what is going on, or when it is required (such as with
357 map() and grep()).
358
359         for (@list) {
360             print;                      # OK; everyone knows this one
361             print uc;                   # wrong; few people know this
362             print uc $_;                # better
363         }
364
365 Note that the special variable C<_> I<should> be used when possible.
366 It is a placeholder that can be passed to stat() and the file test
367 operators, that saves perl a trip to re-stat the file.  In the
368 example below, using C<$file> over for each file test, instead of
369 C<_> for subsequent uses, is a performance hit.  You should be
370 careful that the last-tested file is what you think it is, though.
371
372         if (-d $file) {         # $file is a directory
373             # ...
374         } elsif (-l _) {        # $file is a symlink
375             # ...
376         }
377
378 Package names begin with a capital letter in each word, followed by
379 lower case letters (for the most part).  Multiple words should be StudlyCapped.
380
381         RT::User                        # good
382         RT::Database::MySQL             # proper name
383         RT::Display::Provider           # good
384         RT::CustomField                 # not so good, but OK
385
386 Plugin modules should begin with "RT::Extension::", followed by the name
387 of the plugin.
388
389 =head1 Code formatting
390
391 When in doubt, use perltidy; RT includes a F<.perltidyrc>.
392
393 =head2 Indents and Blank Space
394
395 All indents should be four spaces; hard tabs are forbidden.
396
397 No space before a semicolon that closes a statement.
398
399         foo(@bar) ;     # wrong
400         foo(@bar);      # right
401
402 Line up corresponding items vertically.
403
404         my $foo   = 1;
405         my $bar   = 2;
406         my $xyzzy = 3;
407
408         open(FILE, $fh)   or die $!;
409         open(FILE2, $fh2) or die $!;
410
411         $rot13 =~ tr[abcedfghijklmnopqrstuvwxyz]
412                     [nopqrstuvwxyzabcdefghijklm];
413
414         # note we use a-mn-z instead of a-z,
415         # for readability
416         $rot13 =~ tr[a-mn-z]
417                     [n-za-m];
418
419 Put blank lines between groups of code that do different things.  Put
420 blank lines after your variable declarations.  Put a blank line before a
421 final return() statement.  Put a blank line following a block (and
422 before, with the exception of comment lines).
423
424 An example:
425
426         # this is my function!
427         sub foo {
428             my $val = shift;
429             my $obj = new Constructor;
430             my($var1, $var2);
431
432             $obj->SetFoo($val);
433             $var1 = $obj->Foo();
434
435             return($val);
436         }
437
438         print 1;
439
440
441 =head2 Parentheses
442
443 For control structures, there is a space between the keyword and opening
444 parenthesis.  For functions, there is not.
445
446         for(@list)      # wrong
447         for (@list)     # right
448
449         my ($ref)       # wrong
450         my($ref)        # right
451
452 Be careful about list vs. scalar context with parentheses!
453
454         my @array = ('a', 'b', 'c');
455         my($first_element) = @array;            # a
456         my($first_element) = ('a', 'b', 'c');   # a
457         my $element_count  = @array;            # 3
458         my $last_element   = ('a', 'b', 'c');   # c
459
460 Always include parentheses after functions, even if there are no arguments.
461 There are some exceptions, such as list operators (like print) and unary
462 operators (like undef, delete, uc).
463
464 There is no space inside the parentheses, unless it is needed for
465 readability.
466
467         for ( map { [ $_, 1 ] } @list ) # OK
468         for ( @list )                   # not really OK, not horrible
469
470 On multi-line expressions, match up the closing parenthesis with either
471 the opening statement, or the opening parenthesis, whichever works best.
472 Examples:
473
474         @list = qw(
475             bar
476             baz
477         );                      # right
478
479         if ($foo && $bar && $baz
480                  && $buz && $xyzzy) {
481             print $foo;
482         }
483
484 Whether or not there is space following a closing parenthesis is
485 dependent on what it is that follows.
486
487         print foo(@bar), baz(@buz) if $xyzzy;
488
489 Note also that parentheses around single-statement control expressions,
490 as in C<if $xyzzy>, are optional (and discouraged) C<if> it is I<absolutely>
491 clear -- to a programmer -- what is going on.  There is absolutely no
492 need for parentheses around C<$xyzzy> above, so leaving them out enhances
493 readability.  Use your best discretion.  Better to include them, if
494 there is any question.
495
496 The same essentially goes for perl's built-in functions, when there is
497 nothing confusing about what is going on (for example, there is only one
498 function call in the statement, or the function call is separated by a
499 flow control operator).  User-supplied functions must always include
500 parentheses.
501
502         print 1, 2, 3;                          # good
503         delete $hash{key} if isAnon($uid);      # good
504
505
506 However, if there is any possible confusion at all, then include the
507 parentheses.  Remember the words of Larry Wall in the perlstyle manpage:
508
509         When in doubt, parenthesize.  At the very least it will
510         let some poor schmuck bounce on the % key in vi.
511
512         Even if you aren't in doubt, consider the mental welfare
513         of the person who has to maintain the code after you, and
514         who will probably put parens in the wrong place.
515
516 So leave them out when it is absoutely clear to a programmer, but if
517 there is any question, leave them in.
518
519
520 =head2 Braces
521
522 (This is about control braces, not hash/data structure braces.)
523
524 There is always a space befor the opening brace.
525
526         while (<$fh>){  # wrong
527         while (<$fh>) { # right
528
529 A one-line block may be put on one line, and the semicolon may be
530 omitted.
531
532         for (@list) { print }
533
534 Otherwise, finish each statement with a semicolon, put the keyword and
535 opening curly on the first line, and the ending curly lined up with the
536 keyword at the end.
537
538         for (@list) {
539             print;
540             smell();
541         }
542
543 Generally, we prefer "cuddled elses":
544
545         if ($foo) {
546             print;
547         } else {
548             die;
549         }
550
551 =head2 Operators
552
553 Put space around most operators.  The primary exception is the for
554 aesthetics; e.g., sometimes the space around "**" is ommitted,
555 and there is never a space before a ",", but always after.
556
557         print $x , $y;  # wrong
558         print $x, $y;   # right
559
560         $x = 2 >> 1;    # good
561         $y = 2**2;      # ok
562
563 Note that "&&" and "||" have a higher precedence than "and" and "or".
564 Other than that, they are exactly the same.  It is best to use the lower
565 precedence version for control, and the higher for testing/returning
566 values.  Examples:
567
568         $bool = $flag1 or $flag2;       # WRONG (doesn't work)
569         $value = $foo || $bar;          # right
570         open(FILE, $file) or die $!;
571
572         $true  = foo($bar) && baz($buz);
573         foo($bar) and baz($buz);
574
575 Note that "and" is seldom ever used, because the statement above is
576 better written using "if":
577
578         baz($buz) if foo($bar);
579
580 Most of the time, the confusion between and/&&, or/|| can be alleviated
581 by using parentheses.  If you want to leave off the parentheses then you
582 I<must> use the proper operator.  But if you use parentheses -- and
583 normally, you should, if there is any question at all -- then it doesn't
584 matter which you use.  Use whichever is most readable and aesthetically
585 pleasing to you at the time, and be consistent within your block of code.
586
587 Break long lines AFTER operators, except for ".", "and", "or", "&&", "||".
588 Try to keep the two parts to a binary operator (an operator that
589 has two operands) together when possible.
590
591         print "foo" . "bar" . "baz" .
592               "buz";                            # wrong
593
594         print "foo" . "bar" . "baz"
595             . "buz";                            # right
596
597         print $foo unless $x == 3 && $y ==
598                 4 && $z == 5;                   # wrong
599
600         print $foo unless $x == 3 && $y == 4
601                        && $z == 5;              # right
602
603
604 =head2 Other
605
606 Put space around a complex subscript inside the brackets or braces.
607
608         $foo{$bar{baz}{buz}};   # OK
609         $foo{ $bar{baz}{buz} }; # better
610
611 In general, use single-quotes around literals, and double-quotes
612 when the text needs to be interpolated.
613
614 It is OK to omit quotes around names in braces and when using
615 the => operator, but be careful not to use a name that doubles as
616 a function; in that case, quote.
617
618         $what{'time'}{it}{is} = time();
619
620 When making compound statements, put the primary action first.
621
622         open(FILE, $fh) or die $!;      # right
623         die $! unless open(FILE, $fh);  # wrong
624
625         print "Starting\n" if $verbose; # right
626         $verbose && print "Starting\n"; # wrong
627
628
629 Use here-docs instead of repeated print statements.
630
631                 print <<EOT;
632         This is a whole bunch of text.
633         I like it.  I don't need to worry about messing
634         with lots of print statements and lining them up.
635         EOT
636
637 Just remember that unless you put single quotes around your here-doc
638 token (<<'EOT'), the text will be interpolated, so escape any "$" or "@"
639 as needed.
640
641 =head1 INTERNATIONALIZATION
642
643
644 =head2 String extraction styleguide
645
646 =over 4
647
648 =item Web templates
649
650 Templates should use the /l filtering component to call the localisation
651 framework
652
653 The string              Foo!
654
655 Should become           <&|/l&>Foo!</&>
656
657 All newlines should be removed from localized strings, to make it easy to
658 grep the codebase for strings to be localized
659
660 The string              Foo
661                         Bar
662                         Baz
663
664 Should become           <&|/l&>Foo Bar Baz</&>
665
666
667 Variable subsititutions should be moved to Locale::MakeText format
668
669 The string              Hello, <%$name %>
670
671 should become           <&|/l, $name &>Hello, [_1]</&>
672
673
674 Multiple variables work just like single variables
675
676 The string              You found <%$num%> tickets in queue <%$queue%>
677
678 should become           <&|/l, $num, $queue &>You found [_1] tickets in queue [_2]</&>
679
680 When subcomponents are called in the middle of a phrase, they need to be escaped
681 too:
682
683 The string               <input type="submit" value="New ticket in">&nbsp<& /Elements/SelectNewTicketQueue&>
684
685 should become           <&|/l, $m->scomp('/Elements/SelectNewTicketQueue')&><input type="submit" value="New ticket in">&nbsp;[_1]</&>
686
687
688
689
690 The string      <& /Widgets/TitleBoxStart, width=> "40%", titleright => "RT $RT::VERSION for   RT->Config->Get('rtname')", title => 'Login' &>
691
692 should become   <& /Widgets/TitleBoxStart,
693                         width=> "40%",
694                         titleright => loc("RT [_1] for [_2]",$RT::VERSION, RT->Config->Get('rtname')),
695                         title => loc('Login'),
696                 &>
697
698 =item Library code
699
700
701
702 Within RT's core code, every module has a localization handle available through the 'loc' method:
703
704 The code        return ( $id, "Queue created" );
705
706 should become   return ( $id, $self->loc("Queue created") );
707
708 When returning or localizing a single string, the "extra" set of parenthesis () should be omitted.
709
710 The code        return ("Subject changed to ". $self->Data );
711
712 should become    return $self->loc( "Subject changed to [_1]", $self->Data );
713
714
715 It is important not to localize  the names of rights or statuses within RT's core, as there is logic that depends on them as string identifiers.  The proper place to localize these values is when they're presented for display in the web or commandline interfaces.
716
717
718 =back
719
720 =head1 CODING PRCEDURE
721
722 This is for new programs, modules, specific APIs, or anything else.
723
724 =over 4
725
726 =item Present idea to rt-devel
727
728 We may know of a better way to approach the problem, or know of an
729 existing way to deal with it, or know someone else is working on it.
730 This is mostly informal, but a fairly complete explanation for the need
731 and use of the code should be provided.
732
733
734 =item Present complete specs to rt-devel
735
736 The complete proposed API  should be submitted for
737 approval and discussion.  For web and command-line programs, present the
738 functionality and interface (op codes, command-lin switches, etc.).
739
740 The best way to do this is to take the documentation portion of the
741 boilerplate and fill it in.  You can make changes later if necessary,
742 but fill it in as much as you can.
743
744
745
746 =item Prepare for code review
747
748 When you are done, the code will undergo a code review by a member of
749 the core team, or someone picked by the core team.  This is not to
750 belittle you (that's just a nice side effect), it is to make sure that
751 you understand your code, that we understand your code, that it won't
752 break other code, that it follows the documentation and existing
753 proposal.  It is to check for possible optimizations or better ways of
754 doing it.
755
756 Note that all code is expected to follow the coding principles and style
757 guide contained in this document.
758
759
760 =item Finish it up
761
762 After the code is done (possibly going through multiple code reviews),
763 if you do not have repository access, submit it to rt-bugs@fsck.com as a
764 unified diff. From that point on, it'll be handled by someone with
765 repository access.
766
767 =back
768
769
770 =head1 BUG REPORTS, PATCHES
771
772 Use rt-bugs@bestpractical.com for I<any> bug that is not being fixed
773 immediately.  If it is not in RT, there is a good chance it will not be
774 dealt with.
775
776 Send patches to rt-bugs@bestpractical.com, too.  Use C<diff -u> for
777 patches.
778
779 =head1 SCHEMA DESIGN
780
781 RT uses a convention to denote the foreign key status in its tables.
782 The rule of thumb is:
783
784 =over 4
785
786 =item When it references to another table, always use the table name
787
788 For example, the C<Template> field in the C<Scrips> table refers to
789 the C<Id> of the same-named C<Template> table.
790
791 =item Otherwise, always use the C<Id> suffix
792
793 For example, the C<ObjectId> field in the C<ACL> table can refer
794 to any object, so it has the C<Id> suffix.
795
796 =back
797
798 There are some legacy fields that did not follow this rule, namely
799 C<ACL.PrincipalId>, C<GroupMembers.GroupId> and C<Attachments.TransactionId>,
800 but new tables are expected to be consistent.
801
802
803 =head1 EXTENDING RT CLASSES
804
805 =head2 The Overlay mechanism
806
807 RT's classes allow "overlay" methods to be placed into files named Filename_Vendor.pm and Filename_Local.pm
808 _Vendor is for 3rd-party vendor add-ons, while _Local is for site-local customizations.
809
810 These overlay files can contain new subs or subs to replace existing subs in this module.
811
812 Each of these files should begin with the line
813
814    no warnings qw(redefine);
815
816 so that perl does not kick and scream when you redefine a subroutine or variable in your overlay.
817
818 =head1 TO DO
819
820 Talk about DBIx::SearchBuilder
821
822 Talk about mason
823         component style
824         cascading style sheets
825
826 Talk about adding a new translation
827
828 Talk more about logging