Coding Guidelines

First, read the PHP Coding Standard by Fredrik Kristiansen (who happens to recommend Mantis for bugtracking). The rest of this page describes in which ways we differ, as well as other Mantis-specific guidelines.

Please discuss any omissions or disagreements on our Gitter chat room, or in the Forums.

• Line length: should generally be kept below 80 chars, although it is acceptable to have lines up to 120 chars when necessary.
• Indentations: use TABS with a size of 4 (not spaces)
• PHP tags: always use <?php and ?>, never <? ?> or <?= ?>.

• Use the # symbol for comments. It is visually more distinguishing than // and takes less space.
• Avoid /* */ comment blocks except for the new documentation style for functions/classes, unless you are debugging and testing. Code that is slated for removal maybe also be commented out in this fashion (but leave a note).
• Use phpDocumentor blocks as appropriate
• Use @@@ followed by a brief message (BROKEN, TEMPORARY, etc), or phpDoc's @TODO tag as a “look at this” indicator. Leaving your name next to the tag is a good idea.

• Opening braces { must be on the same line as the construct
• Closing braces } must be directly below the beginning of the construct
• 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 ( in a condition, e.g. if( … not if (
• One space after the opening ( and before the closing ) e.g. while( $i > 0 ) not while($i > 0)
• Arrays elements should be referenced without spaces, e.g. $arr['index'] not $arr[ 'index' ]

Example:

while( while_condition ) {
  ... lots of code ...
  if( blah_condition ) {
    for( ... ) {
    }
    ... lots of code ...
  } # end blah if
  ... lots of code ...
 
  if( cond1 ) {
    something
  } else if( cond2 ) {
    something two
  } else {
    something else
  }
} # end while true

• For equality comparisons, put constants on the left

  if( CONSTANT == $blah ) {
    ...code...
  }

• The NOT operator !should be placed right next to its operand, without space, e.g. !$t_found not ! $t_found
• Add parentheses as appropriate to make things improve readability (even if not syntactically required by operators precedence).

To facilitate reading of complex conditions, you can either:

• Use variables to store sub-conditions

  $t_cond1 = CONSTANT > some_function( arg1, arg2, arg3 );
  $t_cond2 = 0 <= $var1 && 100 > $var1;
  if( $t_cond1 || $t_cond2 ) {
      ...

• Break down the condition over multiple lines, aligning and grouping the conditions

  if(    CONSTANT > some_function( arg1, arg2, arg3 )
      ||     0 <= $var1 
          && 100 > $var1
  ) {
      ...

Every case must have a break or another kind of exit statement, e.g. return, die, etc. If falling through to the following case is intended, it must be documented, unless the case does not contain any code. The break is not necessary for the final, default case.

switch( condition ) {
    case 1:
        blah;
        break;
    case 2:
        blah;
        # Fall through must be commented
    case 3:        # No need for a break here
    case 4:
        blah;
        return;    # No need for a break here
    default:
        blah;
}

• 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 ?:. It should only be used for very simple cases where a normal if/else construct would make code less readable. In complex cases, use of a function is advised.
• The continue and break construct may be used. However, if you are forced into use by design we may wish to rethink the design.
• Keep functions short. We have several ugly functions that are two or three pages long. These are hazards and need to be fixed. Unfortunately, many of them are also extremely complex. Try to simplify them into small helper functions when refactoring code.
• 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)
• 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. Define constants instead.
• Use single quotes around strings, unless double quotes are necessary (i.e. if you have \n or variables that need expanding)

• Use all lower case.
• Use .php file extension
• Use _ to separate words, e.g. view_new_bugs_page.php
• Filenames must be less than 32 characters in length. This plays nice with older file systems like Mac OS.
• Includes should be suffixed by _inc, e.g. view_all_inc.php

Always include the standard header at the top of the file.

• Use CamelCase style, e.g. MantisFormattingPlugin
• Variables that are class objects should have the prefix coo_

• Use all lower case
• Separate words with underscore '_', e.g. $t_green_color_value
• should be 5 words or less
• Should have the name of the API they are in as prefix, e.g. email_send_all(); function that print should be prefixed with print
• <prefix>_is_*() tests something and returns true or false
• <prefix>_ensure_*() tests something and triggers an ERROR if false, return value is undefined (true?) if true
• A function that performs an action should should use a verb as the second token, e.g.:
  • project_add_user()
  • bug_delete_bugnote()
• A function that returns information should use 'get' as the second token, e.g.:
  • bug_get_field()
  • project_get_bug_count()
• “create” and “delete” should be used as verbs in function names when creating or deleting new objects (like users, projects, etc)
• “add” and “remove” should be used a verbs in functions that associate existing objects (like adding a user to a project)
• Document function: summary, description, parameters, return value

• On principle, always use descriptive names, with the appropriate prefix (see below). Exceptions are allowed for loop variables.
• Use all lower case keywords
• Separate words with underscore '_', e.g. $t_green_color_value

• 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. We may remove this.
• 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.

• Good names for count variables are $t_bug_count, $t_enum_count, $t_resolved_count.
• Good names for counters are $t_bug_counter, $t_total_counter.
• We use $i, $k, etc. for loop variables. This is not particularly good practice. A better approach is to use $t_bug_loop, $t_row_loop, etc. Please use the $i style until we come to a consensus. Note that you shouldn't use $l if you should get that far.

• $t_query is used commonly (previsouly, $query, $query2, $query3… were used)
• $t_result follows the same pattern as $t_query. The numbers should correspond.
• $t_row also follows the same pattern as $t_query. The numbers should correspond.

• UPPERCASE all SQL keywords (SELECT, FROM, etc.).
• Always create the query as a variable before sending it to the query function. This allows for simpler debugging.
• Some consideration should be given to making things portable. This is not crucial but will lessen work later.
• Break up SQL queries over multiple lines to make them easier to read.

  $query = "SELECT *
  	FROM $t_bug_table
  	WHERE id='1'";

Tables should be wrapped a table-container:¹⁾

<div class="table-container"><table><!-- ... --></table></div>