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