This is an old revision of the document!


There has been a discussion on new coding standards for PHP5 object orientation on the Mailing list: http://thread.gmane.org/gmane.comp.bug-tracking.mantis.devel/2031/focus=2040

Coding Guidelines

First, read the PHP Coding Standard by Fredrik Kristiansen (who happens to recommend Mantis for bugtracking).

Next we will list the ways in which we differ and other Mantis specific guidelines.

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. The end brace should 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.
while( true ) {
  ... lots of code ...
  if (blah_condition) {
    for (...) {
    }
    ... lots of code ...
  } # end blah if
  ... lots of code ...
 
  if (1) {
    something
  } else if (2) {
    something two
  } else {
    something else
  }
 
} # end while true
  • Tab spacing of 4.
  • We currently use Tabs instead of spaces. Any decent editor will let you set the tab width. I am not opposed to using spaces instead. However there are some extra cons like file size and increased chance of bad formatting and more work to cleanup bad formatting.
  • Limit use of ?: severely. Personally, I hate it unless I know ahead of time what it will be doing. If you do use it I would prefer you a) document what it does (so you might as well use a if/then/else) and b) put it inside a function call.
  • The continue and break construct may be used. However, if you are forced into use by design we may wish to rethink the design.
  • Short functions. 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.
  • Use the # symbol for comments. It is visually more distinguishing than / / and takes less space.
  • Avoid /* */ commenting unless you are debugging and testing. Also code that is slated for removal maybe be commented out in this fashion (but leave a note). (Except for the new documentation style for functions/classes... jreese)
  • Never use <? ?> or <?= ?>. Always use <?php ?>.
  • Avoid magic numbers. Define constants instead. 0 and 1 may be used if you are sure of what you are doing. Places where 0 and/or 1 are used must be examined carefully.
  • User single quotes around strings unless double quotes are necessary (if you have \n or variables that need expanding)
  • For equality comparisons put constants on the left.
if ( CONSTANT == $blah ) {
  ... code...
}

Prefixes

  • g_ for globals.
  • p_ for function parameters.
  • f_ for form variables.
  • v_, v2_ for extract variables.
  • c_ for checked variables.
  • u_ for user variables. We may remove this.
  • t_ for temporary variables.

Do not use q, o, i, or l for prefixes. These are prone to being mistaken for each other or existing prefixes.

Counters and loop variables

  • Good names for count variables are $bug_count, $enum_count, $resolved_count.
  • Good names for counters are $bug_counter, $total_counter.
  • We use $i, $k, etc. for loop variables. This is not particularly good practice. A better approach is to use $bug_loop, $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.

Other variables

  • $query is used commonly as are $query2, $query3... ($t_query is used these days... jreese)
  • $result follows the same pattern as $query. The numbers should correspond. ($t_result is used these days... jreese)
  • $row also follows the same pattern as $query. The numbers should correspond. ($t_row is used these days... jreese)

SQL

  • 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.

Function Names

  • Should begin with the name of the API they are in
  • <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)
 
Logged in as: anonymous
mantisbt/coding_guidelines.1366406915.txt.gz · Last modified: 2013/08/14 18:45 by atrol