Differences

This shows you the differences between two versions of the page.

--- mantisbt:coding_guidelines [2008/04/17 14:50] – daryn
+++ 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://thread.gmane.org/gmane.comp.bug-tracking.mantis.devel/2031/focus=2040
 ====== Coding Guidelines ======
-First, read the [[http://www.dagbladet.no/development/phpcodingstandard/|PHP Coding Standard]] by Fredrik Kristiansen (who happens to recommend Mantis for bugtracking).
+First, read the [[http://www.sourceformat.com/coding-standard-php-kristiansen.htm|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.
-Next we will list the ways in which we differ and other Mantis specific guidelines.
+Please discuss any omissions or disagreements on our [[https://gitter.im/mantisbt/mantisbt|Gitter]] chat room, or in the [[http://mantisbt.org/forums|Forums]].
-Please list any omissions or disagreements.
-  * We aren't using classes and objects.  Exceptions for third party libraries **(Except we do in the bug api, bugnote api, and others... jreese)**
-  * 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.
-<code php>
+===== General Formatting =====
-while( true ) {
+  * 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 ''<?= ?>''.
+===== Comments =====
+  * 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 [[http://phpdoc.org/|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.
+===== Code Blocks =====
+==== Braces and Parentheses ====
+    * 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:<code php>
+while( while_condition ) {
   ... lots of code ...
-  if (blah_condition) {
+  if( blah_condition ) {
-    for (...) {
+    for( ... ) {
     }
     ... lots of code ...
@@ Line 21: / Line 49: @@
   ... lots of code ...
-  if (1) {
+  if( cond1 ) {
     something
-  } else if (2) {
+  } else if( cond2 ) {
     something two
   } else {
     something else
   }
 } # end while true
 </code>
-  * 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.
+==== Conditions ====
-  * 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.
+  * For equality comparisons, put constants on the left <code php>
-  * 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.
+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.  It is visually more distinguishing than / / and takes less space.
+</code>
-  * 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)//**
+  * The NOT operator ''!''should be placed right next to its operand, without space, e.g. ''!$t_found'' not ''! $t_found''
-  * Never use <? ?> or <?= ?>.  Always use <?php ?>.
+  * Add parentheses as appropriate to make things improve readability (even if not syntactically required by operators precedence).
-  * 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)
+To facilitate reading of complex conditions, you can either:
-  * 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 <code php>
+if(    CONSTANT > some_function( arg1, arg2, arg3 )
+    ||     0 <= $var1
+        && 100 > $var1
+) {
+    ...
+</code>
+==== Switch statements ====
+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.
 <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;    # No need for a break here
+    default:
+        blah;
 }
 </code>
-===== 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.  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.
+  * 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)
-===== Counters and loop variables =====
-  * Good names for count variables are $bug_count, $enum_count, $resolved_count.
+===== File Names =====
-  * 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 =====
+  * 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.
-  * $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 =====
+===== 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.  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
+  * 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
@@ Line 96: / Line 155: @@
   * "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)
+  * [[http://phpdoc.org/|Document function]]: summary, description, parameters, return value
+===== Variables Names =====
+  * 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
+==== 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.  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.
+==== Counters and Loop variables ====
+  * 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.
+==== Other Variables ====
+  * $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.
+===== SQL Formatting =====
+  * 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. <code php>
+$query = "SELECT *
+	FROM $t_bug_table
+	WHERE id='1'";
+</code>
+===== CSS =====
+Tables should be wrapped a ''table-container'':((See http://www.mantisbt.org/bugs/view.php?id=16471))
+<code html>
+<div class="table-container"><table><!-- ... --></table></div>
+</code>