User Tools

  • Logged in as: anonymous (anonymous)
  • Log Out

Site Tools


mantisbt:coding_guidelines

This is an old revision of the document!


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.

  • We aren't using classes and objects. Exceptions for third party libraries
  • For global variables we prepend with g_ instead of just g.
  • Use the btrracing policy of putting the first brace on the same line as the construct. The end brace should be directly below the begining of the contruct. 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. Howeever there are some extra cons like file size and increased chance of bad formatting and more work to cleanup bad formatting.
  • Limit use of ?: severly. 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 datbase row fetching. Don't do it.
  • 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). * 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 comparions put constants on the left. If you look carefully you'll notice why this is a good thing. <code php> if ( CONSTANT = $blah ) { … code… } </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… * $result follows the same pattern as $query. The numbers should correspond. * $row also follows the same pattern as $query. The numbers should correspond. ===== 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 shoul be giv3en to making things portable. This is not cruciial 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 and 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)
mantisbt/coding_guidelines.1157957261.txt.gz · Last modified: 2008/10/29 04:31 (external edit)

Driven by DokuWiki