Wiki

User Tools

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

Site Tools

Trace:
mantisbt:coding_guidelines

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
mantisbt:coding_guidelines [2013/08/14 20:00] – Complete review, merge with mantisbt.org/guidelines.php dregadmantisbt:coding_guidelines [2018/04/03 05:50] (current) – [Coding Guidelines] fix broken link to mailing lists page (#24212) dregad
Line 8: Line 8:
 The rest of this page describes in which ways we differ, as well as other Mantis-specific guidelines. 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 the [[http://mantisbt.org/mailinglists.php|Developers Mailing List]].+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 ===== ===== 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)   * Indentations: use TABS with a size of 4 (not spaces)
   * PHP tags: always use ''<?php'' and ''?>'', never ''<? ?>'' or ''<?= ?>''.   * PHP tags: always use ''<?php'' and ''?>'', never ''<? ?>'' or ''<?= ?>''.
Line 18: Line 20:
 ===== Comments ===== ===== Comments =====
  
-  * Use the ''#'' symbol for comments.  It is visually more distinguishing than ''//'' and takes less space. +  * Use the ''#'' symbol for comments.  It is visually more distinguishing than ''%%//%%'' and takes less space. 
-  * Avoid ''/* */'', except for the new documentation style for functions/classes 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).+  * 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 [[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.   * 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.
Line 26: Line 28:
 ===== Code Blocks ===== ===== Code Blocks =====
  
-==== Braces ====+ 
 +==== Braces and Parentheses ====
  
     * Opening braces ''{'' must be on the same line as the construct     * Opening braces ''{'' must be on the same line as the construct
     * Closing braces ''}'' must be directly below the beginning of 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//     * 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//
- 
-==== Parentheses ==== 
  
     * No space before the opening parentheses ''('' in a condition, e.g. ''if( ...'' not ''if (''     * 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)''     * 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  +Example:<code php>
-<code php>+
 while( while_condition ) { while( while_condition ) {
   ... lots of code ...   ... lots of code ...
Line 61: Line 62:
 ==== Conditions ==== ==== Conditions ====
  
-  * For equality comparisons put constants on the left <code php>+  * For equality comparisons, put constants on the left <code php>
 if( CONSTANT == $blah ) { if( CONSTANT == $blah ) {
   ...code...   ...code...
 } }
 </code> </code>
-  * The NOT operator should be placed right next to its operand, without space, e.g. ''!$t_found'' not ''! $t_found''+  * 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).   * Add parentheses as appropriate to make things improve readability (even if not syntactically required by operators precedence).
  
Line 76: Line 77:
 if( $t_cond1 || $t_cond2 ) { if( $t_cond1 || $t_cond2 ) {
     ...     ...
-<code> +</code> 
-  * Break down the condition over multiple lines <code php>+  * Break down the condition over multiple lines, aligning and grouping the conditions <code php>
 if(    CONSTANT > some_function( arg1, arg2, arg3 ) if(    CONSTANT > some_function( arg1, arg2, arg3 )
     ||     0 <= $var1      ||     0 <= $var1 
Line 83: Line 84:
 ) { ) {
     ...     ...
-<code>+</code>
  
  
 ==== Switch statements ==== ==== 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> <code php>
Line 95: Line 98:
     case 2:     case 2:
         blah;         blah;
-        # Fall through should be commented +        # Fall through must be commented 
-    case 3:+    case 3:        # No need for a break here
     case 4:     case 4:
         blah;         blah;
-        break;+        return;    # No need for a break here
     default:     default:
         blah;         blah;
 } }
-<code>+</code>
  
  
Line 184: Line 187:
   * $t_result follows the same pattern as $t_query.  The numbers should correspond.   * $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.   * $t_row also follows the same pattern as $t_query.  The numbers should correspond.
 +
  
  
Line 197: Line 201:
 </code> </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>
mantisbt/coding_guidelines.1376524857.txt.gz · Last modified: 2013/08/14 20:08 (external edit)
CC Attribution-Noncommercial-Share Alike 4.0 International Driven by DokuWiki