mantisbt:coding_guidelines
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
mantisbt:coding_guidelines [2008/10/29 04:25] – (old revision restored) 127.0.0.1 | mantisbt:coding_guidelines [2018/04/03 05:50] (current) – [Coding Guidelines] fix broken link to mailing lists page (#24212) dregad | ||
---|---|---|---|
Line 1: | Line 1: | ||
+ | There has been a discussion on new coding standards for PHP5 object orientation on the Mailing list: | ||
+ | http:// | ||
+ | |||
+ | |||
====== Coding Guidelines ====== | ====== Coding Guidelines ====== | ||
- | First, read the [[http:// | + | First, read the [[http:// |
+ | The rest of this page describes in which ways we differ, as well as other Mantis-specific guidelines. | ||
- | Next we will list the ways in which we differ and other Mantis specific guidelines. | + | Please discuss any omissions or disagreements on our [[https:// |
- | Please list any omissions or disagreements. | ||
- | * For global variables we prepend with g_ instead of just g. | ||
- | * Use the bracing policy of putting the first brace on the same line as the construct. | ||
- | <code php> | + | ===== General Formatting ===== |
- | while( | + | |
+ | * Line length: should generally be kept below **80 chars**, although it is acceptable to have lines up to 120 chars when necessary. | ||
+ | * Indentations: | ||
+ | * PHP tags: always use ''<? | ||
+ | |||
+ | ===== Comments ===== | ||
+ | |||
+ | * Use the ''#'' | ||
+ | * Avoid ''/ | ||
+ | * Use [[http:// | ||
+ | * Use '' | ||
+ | |||
+ | |||
+ | ===== Code Blocks ===== | ||
+ | |||
+ | |||
+ | ==== Braces and Parentheses ==== | ||
+ | |||
+ | * Opening braces '' | ||
+ | * Closing braces '' | ||
+ | * At the end of a long condition or many nested conditions you should place end markers such as //# end for loop// or //# end outermost while// | ||
+ | |||
+ | * No space before the opening parentheses '' | ||
+ | * One space after the opening '' | ||
+ | * Arrays elements should be referenced without spaces, e.g. '' | ||
+ | |||
+ | Example:<code php> | ||
+ | while( | ||
... lots of code ... | ... lots of code ... | ||
- | if (blah_condition) { | + | if( blah_condition ) { |
- | for (...) { | + | for( ... ) { |
} | } | ||
... lots of code ... | ... lots of code ... | ||
Line 20: | Line 49: | ||
... lots of code ... | ... lots of code ... | ||
- | if (1) { | + | if( cond1 ) { |
something | something | ||
- | } else if (2) { | + | } else if( cond2 ) { |
something two | something two | ||
} else { | } else { | ||
something else | something else | ||
} | } | ||
- | |||
} # end while true | } # end while true | ||
</ | </ | ||
- | * Tab spacing of 4. | + | |
- | * We currently use Tabs instead of spaces. | + | ==== Conditions ==== |
- | * Limit use of ?: severely. | + | |
- | | + | * For equality comparisons, |
- | * Short functions. We have several ugly functions that are two or three pages long. These are hazards and need to be fixed. | + | if( CONSTANT == $blah ) { |
- | * Do not use embedded assignments at all. One popular method is in a while loop for database row fetching. Don't do it. **//(Except we do this practically everywhere... jreese)//** | + | ...code... |
- | * Mark unusual comment notes with a @@@ and one of the Gotcha keywords (KLUDGE, TRICKY etc.) You may also want to leave your username. | + | } |
- | * Use the # symbol for comments. | + | </code> |
- | * Avoid /* */ commenting unless you are debugging and testing. | + | * The NOT operator '' |
- | * Never use <? ?> or <?= ?>. | + | |
- | * Avoid magic numbers. | + | |
- | * User single quotes around strings | + | To facilitate reading |
- | * For equality comparisons put constants on the left. If you look carefully you'll notice why this is a good thing. | + | |
+ | * Use variables to store sub-conditions <code php> | ||
+ | $t_cond1 = CONSTANT > some_function( arg1, arg2, arg3 ); | ||
+ | $t_cond2 = 0 <= $var1 && 100 > $var1; | ||
+ | if( $t_cond1 || $t_cond2 ) { | ||
+ | | ||
+ | </code> | ||
+ | * Break down the condition over multiple lines, aligning and grouping the conditions | ||
+ | if( CONSTANT > some_function( arg1, arg2, arg3 ) | ||
+ | || | ||
+ | && 100 > $var1 | ||
+ | ) { | ||
+ | | ||
+ | </code> | ||
+ | |||
+ | |||
+ | ==== Switch statements ==== | ||
+ | |||
+ | Every case //must// have a '' | ||
<code php> | <code php> | ||
- | if ( CONSTANT = $blah ) { | + | switch( condition |
- | ... code... | + | case 1: |
+ | blah; | ||
+ | break; | ||
+ | case 2: | ||
+ | blah; | ||
+ | # Fall through must be commented | ||
+ | case 3: # No need for a break here | ||
+ | case 4: | ||
+ | blah; | ||
+ | return; | ||
+ | default: | ||
+ | blah; | ||
} | } | ||
</ | </ | ||
- | ===== Prefixes ===== | ||
- | * g_ for globals. | + | ===== Miscellaneous ===== |
- | * p_ for function parameters. | + | |
- | * f_ for form variables. | + | |
- | * v_, v2_ for extract variables. | + | |
- | * c_ for checked variables. | + | |
- | * u_ for user variables. | + | |
- | * t_ for temporary variables. | + | |
- | Do not use q, o, i, or l for prefixes. These are prone to being mistaken | + | * Avoid print/echo of HTML unless it's short or in a function loop |
+ | * Do not use the EOF construct | ||
+ | * Severely limit use of ternary operator ''?:'' | ||
+ | * The '' | ||
+ | * Keep functions short. | ||
+ | * Do not use embedded assignments at all. One popular method is in a while loop for database row fetching. | ||
+ | * Mark unusual comment notes with a @@@ and one of the Gotcha keywords (KLUDGE, TRICKY etc.) You may also want to leave your username. | ||
+ | * Avoid magic numbers at all costs. | ||
+ | * Use single quotes around strings, unless double quotes are necessary (i.e. if you have '' | ||
- | ===== Counters and loop variables ===== | ||
- | * Good names for count variables are $bug_count, $enum_count, | + | ===== File Names ===== |
- | * Good names for counters are $bug_counter, | + | |
- | * We use $i, $k, etc. for loop variables. | + | |
- | ===== Other variables ===== | + | * Use all lower case. |
+ | * Use '' | ||
+ | * Use '' | ||
+ | * Filenames must be less than 32 characters in length. | ||
+ | * Includes should be suffixed by '' | ||
+ | Always include the standard header at the top of the file. | ||
- | * $query is used commonly as are $query2, $query3... | ||
- | * $result follows the same pattern as $query. | ||
- | * $row also follows the same pattern as $query. | ||
- | ===== SQL ===== | + | ===== Classes Names ===== |
+ | |||
+ | * Use CamelCase style, e.g. MantisFormattingPlugin | ||
+ | * Variables that are class objects should have the prefix coo_ | ||
- | * UPPERCASE all SQL keywords (SELECT, FROM, etc.). | ||
- | * Always create the query as a variable before sending it to the query function. | ||
- | * Some consideration should be given to making things portable. | ||
===== Function Names ===== | ===== Function Names ===== | ||
- | * Should begin with the name of the API they are in | + | * Use all lower case |
+ | * Separate words with underscore ' | ||
+ | * should be 5 words or less | ||
+ | * Should have the name of the API they are in as prefix, e.g. email_send_all(); | ||
* < | * < | ||
* < | * < | ||
Line 95: | Line 155: | ||
* " | * " | ||
* " | * " | ||
+ | * [[http:// | ||
+ | |||
+ | |||
+ | ===== Variables Names ===== | ||
+ | |||
+ | * On principle, always use descriptive names, with the appropriate prefix (see below). | ||
+ | * Use all lower case keywords | ||
+ | * Separate words with underscore ' | ||
+ | |||
+ | ==== Prefixes ==== | ||
+ | |||
+ | * g_ for globals. | ||
+ | * p_ for function parameters. | ||
+ | * f_ for (uncleaned) form variables. | ||
+ | * v_, v2_ for extract variables. | ||
+ | * c_ for checked variables (e.g. parameters passed from forms that have been cleaned of any special SQL chars such as slashes) | ||
+ | * u_ for user variables. | ||
+ | * t_ for temporary variables. | ||
+ | |||
+ | Do not use q, o, i, or l for prefixes as they are visually confusing and prone to being mistaken for each other or existing prefixes. | ||
+ | |||
+ | ==== Counters and Loop variables ==== | ||
+ | |||
+ | * Good names for count variables are $t_bug_count, | ||
+ | * Good names for counters are $t_bug_counter, | ||
+ | * We use $i, $k, etc. for loop variables. | ||
+ | |||
+ | ==== Other Variables ==== | ||
+ | |||
+ | * $t_query is used commonly (previsouly, | ||
+ | * $t_result follows the same pattern as $t_query. | ||
+ | * $t_row also follows the same pattern as $t_query. | ||
+ | |||
+ | |||
+ | |||
+ | ===== SQL Formatting ===== | ||
+ | |||
+ | * UPPERCASE all SQL keywords (SELECT, FROM, etc.). | ||
+ | * Always create the query as a variable before sending it to the query function. | ||
+ | * Some consideration should be given to making things portable. | ||
+ | * Break up SQL queries over multiple lines to make them easier to read. <code php> | ||
+ | $query = " | ||
+ | FROM $t_bug_table | ||
+ | WHERE id=' | ||
+ | </ | ||
+ | |||
+ | ===== CSS ===== | ||
+ | |||
+ | Tables should be wrapped a '' | ||
+ | |||
+ | <code html> | ||
+ | <div class=" | ||
+ | </ |
mantisbt/coding_guidelines.1225268720.txt.gz · Last modified: 2009/02/26 11:43 (external edit)