Differences

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

--- mantisbt:coding_guidelines [2008/04/17 20:20] – We now use more OO after moving to PHP 5 vboctor
+++ mantisbt:coding_guidelines [2025/01/11 10:16] (current) – [Coding Guidelines] fallback to PHP-FIG PER Coding Style 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.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.
+If something is not defined in this document, then please apply the rules in PHP-FIG's [[https://www.php-fig.org/per/coding-style/|PER Coding Style]] as fallback.
+Please discuss any omissions or disagreements on our [[https://gitter.im/mantisbt/mantisbt|Gitter]] chat room, or in the [[http://mantisbt.org/forums|Forums]].
+===== General Formatting =====
+  * 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 ) {
+    for( ... ) {
+    }
+    ... lots of code ...
+  } # end blah if
+  ... lots of code ...
+  if( cond1 ) {
+    something
+  } else if( cond2 ) {
+    something two
+  } else {
+    something else
+  }
+} # end while true
+</code>
+==== Conditions ====
+  * For equality comparisons, put constants on the left <code php>
+if( CONSTANT == $blah ) {
+  ...code...
+}
+</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 <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>
+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;
+}
+</code>
+===== Miscellaneous =====
+  * 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)
+===== File Names =====
+  * 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.
+===== Classes Names =====
+  * Use CamelCase style, e.g. MantisFormattingPlugin
+  * Variables that are class objects should have the prefix coo_
+===== Function Names =====
+  * 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)
+  * [[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>