Audean Wiki

User Tools

Site Tools

You are here: Audean Wiki for Mediacore services » Coding conventions - standards for OSInet-originated PHP and HTML code
Trace:
coding

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
coding [2008/04/17 21:56] – fgmcoding [2020/11/23 17:23] (current) – external edit 127.0.0.1
Line 15: Line 15:
  
 ====== Indenting ====== ====== Indenting ======
 +
  
  
Line 35: Line 36:
  
 ===== Function Declarations ===== ===== Function Declarations =====
- 
- 
  
 <html> <html>
- 
 <table class="inline" style="width: 100%"> <table class="inline" style="width: 100%">
- 
   <tr>   <tr>
- 
     <th>OSInet</th>     <th>OSInet</th>
- 
     <th>Drupal</th>     <th>Drupal</th>
- 
     <th>PEAR</th>     <th>PEAR</th>
- 
     <th>ZF</th>     <th>ZF</th>
- 
     </tr>     </tr>
- +  <tr style="white-space: pre; font-family: monospace;"><td style="vertical-align: top">private function foo($bar, $baz = 'qux') 
-  <tr style="white-space: pre; font-family: monospace;"> +
- +
-    <td style="vertical-align: top">private function foo($bar, $baz = 'qux')  +
   {   {
- 
   $ret = action;   $ret = action;
- 
   return $ret;   return $ret;
- +  }</td><td style="vertical-align: top">function _g2_foo($bar, $baz = 'qux') {
-  }</td> +
- +
-    <td style="vertical-align: top">function _g2_foo($bar, $baz = 'qux') { +
   return action;   return action;
- +}</td><td colspan="2" style="vertical-align: top">private function foo($bar, $baz = 'qux')
-}</td> +
- +
-      <td colspan="2" style="vertical-align: top">private function foo($bar, $baz = 'qux') +
     {     {
- 
         return action;         return action;
- 
     }</td>     }</td>
- 
       </tr>       </tr>
- 
     </table>     </table>
- 
   </html>   </html>
- 
- 
  
 Arguments with default values go at the end of the argument list. Always attempt to return a meaningful value from a function if one is appropriate. Never use parentheses around the returned value (ZF: it can break code if a method is later changed to return by reference). Arguments with default values go at the end of the argument list. Always attempt to return a meaningful value from a function if one is appropriate. Never use parentheses around the returned value (ZF: it can break code if a method is later changed to return by reference).
- 
- 
  
 For long argument lists or long argument names, appropriate line wrapping may be used, like: For long argument lists or long argument names, appropriate line wrapping may be used, like:
- 
 <code php> <code php>
- 
 public function someFunctionWithALongName( public function someFunctionWithALongName(
- 
   $firstParamsHasALongNameToo,   $firstParamsHasALongNameToo,
- 
   $secondParamIsAlmostWorse   = 'default',   $secondParamIsAlmostWorse   = 'default',
- 
   $notForgettingOtherDefaults = 0)   $notForgettingOtherDefaults = 0)
- 
   {   {
- 
   $ret = action;   $ret = action;
- 
   return $ret;   return $ret;
- 
   }   }
- 
 </code> </code>
 +
  
  
  
 ===== Class Declarations ===== ===== Class Declarations =====
- 
- 
- 
- 
  
 <html> <html>
- 
 <table class="inline" style="width: 100%"> <table class="inline" style="width: 100%">
- 
   <tr>   <tr>
- 
     <th>OSInet</th>     <th>OSInet</th>
- 
     <th>Drupal</th>     <th>Drupal</th>
- 
     <th>PEAR</th>     <th>PEAR</th>
- 
     <th>ZF</th>     <th>ZF</th>
- 
     </tr>     </tr>
- +  <tr style="white-space: pre; font-family: monospace;"><td style="vertical-align: top">class Foo
-  <tr style="white-space: pre; font-family: monospace;"> +
- +
-    <td style="vertical-align: top">class Foo +
   {   {
- 
   // members   // members
- +  }</td><td style="vertical-align: top">N.A: no classes</td><td>?</td><td style="vertical-align: top">class Foo
-  }</td> +
- +
-    <td style="vertical-align: top">N.A: no classes</td> +
- +
-      <td>?</td> +
- +
-    <td style="vertical-align: top">class Foo +
 { {
- 
     // members     // members
- 
 }</td> }</td>
- 
       </tr>       </tr>
- 
     </table>     </table>
- 
   </html>   </html>
- 
- 
- 
  
  
 ===== if / then / else ===== ===== if / then / else =====
- 
- 
  
 <html> <html>
- 
 <table class="inline" style="width: 100%"> <table class="inline" style="width: 100%">
- 
   <tr>   <tr>
- 
     <th>OSInet</th>     <th>OSInet</th>
- 
     <th>Drupal</th>     <th>Drupal</th>
- 
     <th>PEAR</th>     <th>PEAR</th>
- 
     <th>ZF</th>     <th>ZF</th>
- 
     </tr>     </tr>
- +  <tr style="white-space: pre; font-family: monospace;"><td style="vertical-align: top">if (test1 || test2)
-  <tr style="white-space: pre; font-family: monospace;"> +
- +
-    <td style="vertical-align: top">if (test1 || test2) +
   {   {
- 
   action1;   action1;
- 
   }   }
- 
 elseif (test3 && test2) elseif (test3 && test2)
- 
   {   {
- 
   action2;   action2;
- 
   }   }
- 
 else  else 
- 
   {   {
- 
   defaultaction;   defaultaction;
- +  }</td><td style="vertical-align: top">if (test1 || test2) {
-  }</td> +
- +
-    <td style="vertical-align: top">if (test1 || test2) { +
   action1;   action1;
- 
 } }
- 
 elseif (test3 && test4) { elseif (test3 && test4) {
- 
   action2;   action2;
- 
 } }
- 
 else { else {
- 
   defaultaction;   defaultaction;
- +}</td><td style="vertical-align: top">if ((test1) || (test2)) {
-}</td> +
- +
-    <td style="vertical-align: top">if ((test1) || (test2)) { +
     action1;     action1;
- 
 } elseif ((test3) && (test4)) { } elseif ((test3) && (test4)) {
- 
     action2;     action2;
- 
 } else { } else {
- 
     defaultaction;     defaultaction;
- +}</td><td style="vertical-align: top">if (test1) {
-}</td> +
- +
-    <td style="vertical-align: top">if (test1) { +
     action1;     action1;
- 
 } else if (test3) { } else if (test3) {
- 
    action2;    action2;
- 
 } else { } else {
- 
    defaultaction;    defaultaction;
- +}</td></tr>
-}</td> +
- +
-    </tr> +
   <tr>   <tr>
- 
     <td>&nbsp;</td>     <td>&nbsp;</td>
- 
     <td><a href="http://drupal.org/node/318">Control structures</a></td>     <td><a href="http://drupal.org/node/318">Control structures</a></td>
- 
     <td><a href="http://pear.php.net/manual/en/standards.control.php">Control structures</a></td>     <td><a href="http://pear.php.net/manual/en/standards.control.php">Control structures</a></td>
- 
     <td>derived from §A.4.6.1.</td>     <td>derived from §A.4.6.1.</td>
- 
   </table>   </table>
- 
 </html> </html>
- 
- 
  
 Note that for ZF, the code sample supplied in the doc contradicts the doc text. Reference is made to the text. The rules and sample do not specify parenthesing for multiple tests in a clause. Note that for ZF, the code sample supplied in the doc contradicts the doc text. Reference is made to the text. The rules and sample do not specify parenthesing for multiple tests in a clause.
- 
- 
  
 For OSInet, long tests must be wrapped to align readably. Although ZF does not mention this, the line length requirement makes it likely too. For OSInet, long tests must be wrapped to align readably. Although ZF does not mention this, the line length requirement makes it likely too.
- 
  
  
 ===== switch ===== ===== switch =====
- 
- 
  
 <html> <html>
- 
 <table class="inline" style="width: 100%"> <table class="inline" style="width: 100%">
- 
   <tr>   <tr>
- 
     <th>OSInet</th>     <th>OSInet</th>
- 
     <th>Drupal</th>     <th>Drupal</th>
- 
     <th>PEAR</th>     <th>PEAR</th>
- 
     <th>ZF</th>     <th>ZF</th>
- 
     </tr>     </tr>
- +    <tr style="white-space: pre; font-family: monospace"><td style="vertical-align: top">switch (condition) 
-    <tr style="white-space: pre; font-family: monospace"> +
- +
-      <td style="vertical-align: top">switch (condition)  +
   {   {
- 
   case 1:   case 1:
- 
     action1;     action1;
- 
     break;     break;
- 
- 
  
   case 2:   case 2:
- 
     action2;     action2;
- 
     break;     break;
- 
- 
  
   default:   default:
- 
     defaultaction;     defaultaction;
- 
     break;     break;
- +  }</td><td style="vertical-align: top">switch (condition) {
-  }</td> +
- +
-      <td style="vertical-align: top">switch (condition) { +
   case 1:   case 1:
- 
     action1;     action1;
- 
     break;     break;
- 
- 
  
   case 2:   case 2:
- 
     action2;     action2;
- 
     break;     break;
- 
- 
  
   default:   default:
- 
     defaultaction;     defaultaction;
- 
     break;     break;
- +}</td><td style="vertical-align: top">switch (condition) {
-}</td> +
- +
-      <td style="vertical-align: top">switch (condition) { +
 case 1: case 1:
- 
     action1;     action1;
- 
     break;     break;
- 
- 
  
 case 2: case 2:
- 
     action2;     action2;
- 
     break;     break;
- 
- 
  
 default: default:
- 
     defaultaction;     defaultaction;
- 
     break;     break;
- +}</td><td style="vertical-align: top">switch (condition) {
-}</td> +
- +
-      <td style="vertical-align: top">switch (condition) { +
     case 1:     case 1:
- 
         break;         break;
- 
- 
  
     case 2:     case 2:
- 
         break;         break;
- 
- 
  
     default:     default:
- 
         break;         break;
- +}</td></tr>
-}</td> +
- +
-    </tr> +
   </table>   </table>
- 
 </html> </html>
- 
  
  
 ===== General table ===== ===== General table =====
- 
- 
  
 ^ Category ^  OSInet  ^  Drupal  ^  PEAR    ^  ZF      ^ ^ Category ^  OSInet  ^  Drupal  ^  PEAR    ^  ZF      ^
- 
 ^ Spacing  | Control statements should have one space between the control keyword and opening parenthesis, to distinguish them from function calls. ||| Control statements based on the if and elseif constructs must have a single space before the opening parenthesis of the conditional, | ^ Spacing  | Control statements should have one space between the control keyword and opening parenthesis, to distinguish them from function calls. ||| Control statements based on the if and elseif constructs must have a single space before the opening parenthesis of the conditional, |
- 
 ^ ... terminal |  n.a.                ||| ... and a single space after the closing parenthesis. | ^ ... terminal |  n.a.                ||| ... and a single space after the closing parenthesis. |
- 
 ^ Bracing  | always use curly braces even in situations where they are technically optional |||  n.a.  | ^ Bracing  | always use curly braces even in situations where they are technically optional |||  n.a.  |
- 
 ^ ... control, opening | The opening brace is written on the line below the structure. |  n.a.  || The opening brace is written on the same line as the conditional statement.  | ^ ... control, opening | The opening brace is written on the line below the structure. |  n.a.  || The opening brace is written on the same line as the conditional statement.  |
- 
 ^ ... control, closing |  = ZF  |  n.a.  || The closing brace is always written on its own line.  | ^ ... control, closing |  = ZF  |  n.a.  || The closing brace is always written on its own line.  |
- 
 ^ ... classes |  = ZF  |  n.a.  || The brace is always written on the line underneath the class name.  | ^ ... classes |  = ZF  |  n.a.  || The brace is always written on the line underneath the class name.  |
 +
  
  
Line 443: Line 232:
  
 ====== Function Calls ====== ====== Function Calls ======
- 
- 
  
 ^ Category  ^  OSInet  ^  Drupal  ^  PEAR    ^  ZF      ^ ^ Category  ^  OSInet  ^  Drupal  ^  PEAR    ^  ZF      ^
- 
 ^ name to ( |  no space  |||| ^ name to ( |  no space  ||||
- 
 ^ ( to arg1 |  no space  |||| ^ ( to arg1 |  no space  ||||
- 
 ^ arg to ,  |  no space  |||| ^ arg to ,  |  no space  ||||
- 
 ^ , to arg  | usually 1 space. May vertically align for block-related function calls |  1 space  ||| ^ , to arg  | usually 1 space. May vertically align for block-related function calls |  1 space  |||
- 
 ^ arg to )  |  no space  |||| ^ arg to )  |  no space  ||||
- 
 ^ ) to ;    |  no space  |||| ^ ) to ;    |  no space  ||||
- 
- 
  
 ZF rules for this are implied by the example in the A.4.5.2 section. ZF rules for this are implied by the example in the A.4.5.2 section.
- 
- 
- 
  
  
 ====== Arrays ====== ====== Arrays ======
- 
- 
  
 Spacing, one-liner: **identical** Spacing, one-liner: **identical**
- 
- 
- 
 Spacing, indented: **Different** Spacing, indented: **Different**
- 
- 
  
 Note that if the line spans longer than 80 characters (often the case with form and menu declarations), each element should be broken into its own line, and indented one level. "=>" symbols ought to be aligned. Note that if the line spans longer than 80 characters (often the case with form and menu declarations), each element should be broken into its own line, and indented one level. "=>" symbols ought to be aligned.
- 
- 
  
 <code php> <code php>
- 
 $form['title'] = array $form['title'] = array
- 
   (   (
- 
   '#type'        => 'textfield',   '#type'        => 'textfield',
- 
   '#title'       => t('Title'),   '#title'       => t('Title'),
- 
   '#size'        => 60,   '#size'        => 60,
- 
   '#maxlength'   => 128,   '#maxlength'   => 128,
- 
   '#description' => t('The title of your node.'),   '#description' => t('The title of your node.'),
- 
   );   );
- 
 </code> </code>
- 
- 
  
 Additional comma: identical. Additional comma: identical.
- 
- 
- 
- 
- 
- 
- 
- 
  
 ====== Including Code ====== ====== Including Code ======
Line 525: Line 273:
  
 This means that including can make use of the autoload mechanism, which can be more efficient under caching than using require_once with conditional content. This means that including can make use of the autoload mechanism, which can be more efficient under caching than using require_once with conditional content.
 +
  
  
Line 543: Line 292:
  
 ====== File formatting ====== ====== File formatting ======
- 
- 
  
 ^ Feature     ^  OSInet    ^  Drupal             ^  PEAR      ^  ZF        ^ ^ Feature     ^  OSInet    ^  Drupal             ^  PEAR      ^  ZF        ^
- 
 | <% %> tags  |  No        |  No                 |  ?         |  ?         | | <% %> tags  |  No        |  No                 |  ?         |  ?         |
- 
 | <? ?> tags  |  No        |  No                 |  ?         |  ?         | | <? ?> tags  |  No        |  No                 |  ?         |  ?         |
- 
 | Closing ?>  |  No        |  Should be omitted  |  ?         |  No        | | Closing ?>  |  No        |  Should be omitted  |  ?         |  No        |
- 
 | Indenting   |  2 spaces  |  2 spaces           |  4 spaces  |  4 spaces  | | Indenting   |  2 spaces  |  2 spaces           |  4 spaces  |  4 spaces  |
- 
 | Tabs        |  No        |  No                 |  No        |  No        |  | Tabs        |  No        |  No                 |  No        |  No        | 
- 
 | Line length |  as ZF     |  unspecified        |  ?         |  Strive for 80  \\  Maximum 120  | | Line length |  as ZF     |  unspecified        |  ?         |  Strive for 80  \\  Maximum 120  |
- 
 | Line termination  |  \n recommended  |  unspecified  |  ?    |  \n mandatory  \\  \r and \r\n forbidden  | | Line termination  |  \n recommended  |  unspecified  |  ?    |  \n mandatory  \\  \r and \r\n forbidden  |
- 
 | __HALT_COMPILER() |  unspecified  |  unspecified     |  ?    |  Forbidden, except in special install files  | | __HALT_COMPILER() |  unspecified  |  unspecified     |  ?    |  Forbidden, except in special install files  |
- 
- 
  
 The rule regarding the closing ?> tag is only applicable to "program-type" PHP files, not to HTML pages with embedded PHP, which are mostly out of the scope of these rules. The rule regarding the closing ?> tag is only applicable to "program-type" PHP files, not to HTML pages with embedded PHP, which are mostly out of the scope of these rules.
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
  
  
 ====== Comments, inline doc ====== ====== Comments, inline doc ======
- 
- 
  
 <html> <html>
- 
   <table class="inline">   <table class="inline">
- 
     <tr>     <tr>
- 
       <th>Category</th>       <th>Category</th>
- 
       <th>OSInet</th>       <th>OSInet</th>
- 
       <th>Drupal</th>       <th>Drupal</th>
- 
       <th>PEAR</th>       <th>PEAR</th>
- 
       <th>ZF</th>       <th>ZF</th>
- 
       </tr>       </tr>
- 
     <tr>     <tr>
- 
       <td>Documentation format</td>       <td>Documentation format</td>
- 
       <td>PHPDocumentor</td>       <td>PHPDocumentor</td>
- 
       <td>Doxygen</td>       <td>Doxygen</td>
- 
       <td>?</td>       <td>?</td>
- 
       <td>PHPDocumentor</td>       <td>PHPDocumentor</td>
- 
       </tr>       </tr>
- 
     <tr>     <tr>
- 
       <td>File header</td>       <td>File header</td>
- 
       <td style="vertical-align: top; text-alignment: left; font-family: monospace">like ZF, but       <td style="vertical-align: top; text-alignment: left; font-family: monospace">like ZF, but
- 
         <ul>         <ul>
- 
           <li>use CeCill 2.0 license if possible</li>           <li>use CeCill 2.0 license if possible</li>
- 
           <li>@package and @subpackage tags to group files</li>           <li>@package and @subpackage tags to group files</li>
- 
           <li>see tag to cross-refer elements</li>           <li>see tag to cross-refer elements</li>
- 
           <li>@version tag can use other VCS' equivalents to CVS' $Id$           <li>@version tag can use other VCS' equivalents to CVS' $Id$
- 
           </ul>           </ul>
- 
        </td>        </td>
- 
       <td style="vertical-align: top; text-alignment: left; font-family: monospace">       <td style="vertical-align: top; text-alignment: left; font-family: monospace">
- 
         <pre>// $Id$         <pre>// $Id$
- 
         </pre>use GPL 2.0 license for core and preferably GPL 2.0 for contrib too</td>         </pre>use GPL 2.0 license for core and preferably GPL 2.0 for contrib too</td>
- 
       <td style="vertical-align: top; text-alignment: left; white-space: pre; font-family: monospace">?</td>       <td style="vertical-align: top; text-alignment: left; white-space: pre; font-family: monospace">?</td>
- 
       <td style="vertical-align: top; text-alignment: left; white-space: pre; font-family: monospace">/**       <td style="vertical-align: top; text-alignment: left; white-space: pre; font-family: monospace">/**
- 
  * Short description for file  * Short description for file
- 
  *  *
- 
  * Long description for file (if any)...  * Long description for file (if any)...
- 
  *  *
- 
  * LICENSE: Some license information  * LICENSE: Some license information
- 
  *  *
- 
  * @copyright  2005 Zend Technologies  * @copyright  2005 Zend Technologies
- 
  * @license    http://www.zend.com/license/3_0.txt   PHP License 3.0  * @license    http://www.zend.com/license/3_0.txt   PHP License 3.0
- 
  * @version    CVS: $Id:$  * @version    CVS: $Id:$
- 
  * @link       http://dev.zend.com/package/PackageName  * @link       http://dev.zend.com/package/PackageName
- 
  * @since      File available since Release 1.2.0  * @since      File available since Release 1.2.0
- 
 */</td> */</td>
- 
       </tr>       </tr>
- 
     <tr>     <tr>
- 
       <td>File header for class file</td>       <td>File header for class file</td>
- 
       <td>as ZF, except @version, use $Id$</td>       <td>as ZF, except @version, use $Id$</td>
- 
       <td>N.A.: no classes</td>       <td>N.A.: no classes</td>
- 
       <td>?</td>       <td>?</td>
- 
       <td style="vertical-align: top; text-alignment: left; white-space: pre; font-family: monospace">/**       <td style="vertical-align: top; text-alignment: left; white-space: pre; font-family: monospace">/**
- 
  * Short description for class  * Short description for class
- 
  *  *
- 
  * Long description for class (if any)...  * Long description for class (if any)...
- 
  *  *
- 
  * @copyright  2005 Zend Technologies  * @copyright  2005 Zend Technologies
- 
  * @license    http://www.zend.com/license/3_0.txt   PHP License 3.0  * @license    http://www.zend.com/license/3_0.txt   PHP License 3.0
- 
  * @version    Release: @package_version@  * @version    Release: @package_version@
- 
  * @link       http://dev.zend.com/package/PackageName  * @link       http://dev.zend.com/package/PackageName
- 
  * @since      Class available since Release 1.2.0  * @since      Class available since Release 1.2.0
- 
  * @deprecated Class deprecated in Release 2.0.0  * @deprecated Class deprecated in Release 2.0.0
- 
  */</td>  */</td>
- 
       </tr>       </tr>
- 
     <tr>     <tr>
- 
       <td>Function header</td>       <td>Function header</td>
- 
       <td>as ZF</td>       <td>as ZF</td>
- 
       <td>unspecified</td>       <td>unspecified</td>
- 
       <td>?</td>       <td>?</td>
- 
       <td>       <td>
- 
         <ul>         <ul>
- 
           <li>Textual description</li>           <li>Textual description</li>
- 
           <li>all @param</li>           <li>all @param</li>
- 
           <li>@return</li>           <li>@return</li>
- 
           <li>@throws if the function throws an exception</li>           <li>@throws if the function throws an exception</li>
- 
           <li>@access now obsoleted by visibility attributes</li>           <li>@access now obsoleted by visibility attributes</li>
- 
           </ul>           </ul>
- 
         </td>         </td>
- 
     </table>     </table>
- 
   </html>    </html> 
- 
- 
- 
- 
  
  
Line 769: Line 412:
  
 ====== Naming Conventions ====== ====== Naming Conventions ======
 +
 +
  
  
Line 791: Line 436:
  
 <html> <html>
- 
   <table class="inline" style="width: 100%">   <table class="inline" style="width: 100%">
- 
     <col span="5" align="left" />     <col span="5" align="left" />
- 
     <tr>     <tr>
- 
       <th>Element</th>       <th>Element</th>
- 
       <th>OSInet</th>       <th>OSInet</th>
- 
       <th>Drupal</th>       <th>Drupal</th>
- 
       <th>PEAR</th>       <th>PEAR</th>
- 
       <th>ZF</th>       <th>ZF</th>
- 
       </tr>       </tr>
- 
     <tr style="vertical-align: top">     <tr style="vertical-align: top">
- 
       <td>Functions</td>       <td>Functions</td>
- +      <td>as ZF</td>
-      <td style="font-family: monospace">getElementById()</td> +
       <td style="font-family: monospace">g2_get_element_by_id()</td>       <td style="font-family: monospace">g2_get_element_by_id()</td>
- 
       <td style="font-family: monospace">?</td>       <td style="font-family: monospace">?</td>
- 
       <td style="font-family: monospace">getElementById()</td>       <td style="font-family: monospace">getElementById()</td>
- 
       </tr>       </tr>
- 
     <tr style="vertical-align: top">     <tr style="vertical-align: top">
- 
       <td>Function scope</td>       <td>Function scope</td>
- 
       <td>as ZF</td>       <td>as ZF</td>
- 
       <td>No classes, so use "&lt;module_name&gt;_" as a namespace to avoid name collision</td>       <td>No classes, so use "&lt;module_name&gt;_" as a namespace to avoid name collision</td>
- 
       <td>?</td>       <td>?</td>
- 
       <td>Floating functions are discouraged. Use a static class.</td>       <td>Floating functions are discouraged. Use a static class.</td>
- 
       </tr>       </tr>
- 
     <tr style="vertical-align: top">     <tr style="vertical-align: top">
- 
       <td>Accessors</td>       <td>Accessors</td>
- 
       <td>as ZF</td>       <td>as ZF</td>
- 
       <td>N.A.: no classes</td>       <td>N.A.: no classes</td>
- 
       <td>?</td>       <td>?</td>
- 
       <td style="font-family: monospace">getSomeField<br />setSomeField</td>       <td style="font-family: monospace">getSomeField<br />setSomeField</td>
- 
       </tr>       </tr>
- 
     <tr style="vertical-align: top">     <tr style="vertical-align: top">
- 
       <td>Design patterns</td>       <td>Design patterns</td>
- 
       <td>as ZF</td>       <td>as ZF</td>
- 
       <td>unspecified</td>       <td>unspecified</td>
- 
       <td>?</td>       <td>?</td>
- 
       <td>Include name of pattern in the name of the method, where practical</td>       <td>Include name of pattern in the name of the method, where practical</td>
- 
       </tr>       </tr>
- 
     <tr>     <tr>
- 
       <td>Constants</td>       <td>Constants</td>
- 
       <td style="white-space: pre; font-family: monospace; vertical-align: top">class G2       <td style="white-space: pre; font-family: monospace; vertical-align: top">class G2
- 
   {   {
- 
   const SOME_CONSTANT = 'foo';   const SOME_CONSTANT = 'foo';
- 
   }</td>   }</td>
- 
       <td style="white-space: pre; font-family: monospace; vertical-align: top">define('G2_SOME_CONSTANT', 'foo');</td>       <td style="white-space: pre; font-family: monospace; vertical-align: top">define('G2_SOME_CONSTANT', 'foo');</td>
- 
       <td style="white-space: pre; font-family: monospace; vertical-align: top">?</td>       <td style="white-space: pre; font-family: monospace; vertical-align: top">?</td>
- 
       <td style="white-space: pre; font-family: monospace; vertical-align: top">class G2 {       <td style="white-space: pre; font-family: monospace; vertical-align: top">class G2 {
- 
   const SOME_CONSTANT = 'foo';   const SOME_CONSTANT = 'foo';
- 
 }</td> }</td>
- 
       </tr>       </tr>
- 
     <tr>     <tr>
- 
       <td>Class fields</td>       <td>Class fields</td>
- 
       <td style="white-space: pre; font-family: monospace; vertical-align: top">private   _someFieldOne;       <td style="white-space: pre; font-family: monospace; vertical-align: top">private   _someFieldOne;
- 
 protected _someFieldTwo; protected _someFieldTwo;
- 
 public    someFieldThree;</td> public    someFieldThree;</td>
- 
       <td style="vertical-align: top">PHP4 pseudo-private field: _some_field</td>       <td style="vertical-align: top">PHP4 pseudo-private field: _some_field</td>
- 
       <td style="vertical-align: top">?</td>       <td style="vertical-align: top">?</td>
- 
       <td style="white-space: pre; font-family: monospace; vertical-align: top">private _someFieldOne;       <td style="white-space: pre; font-family: monospace; vertical-align: top">private _someFieldOne;
- 
 protected _someFieldTwo; protected _someFieldTwo;
- 
 public someFieldThree;</td> public someFieldThree;</td>
- 
       </tr>       </tr>
- 
     <tr>     <tr>
- 
       <td>Global variables</td>       <td>Global variables</td>
- 
       <td>no specific rule</td>       <td>no specific rule</td>
- 
       <td>_g2_some_variable</td>       <td>_g2_some_variable</td>
- 
       <td>?</td>       <td>?</td>
- 
       <td>no specific rule</td>       <td>no specific rule</td>
- 
       </tr>       </tr>
- 
     <tr>     <tr>
- 
       <td>Code files</td>       <td>Code files</td>
- 
       <td style="vertical-align: top">       <td style="vertical-align: top">
- 
         <ul>         <ul>
- 
           <li>Drupal components: as Drupal</li>           <li>Drupal components: as Drupal</li>
- 
           <li>elsewhere: as ZF</li>           <li>elsewhere: as ZF</li>
- 
           </ul>           </ul>
- 
         </td>         </td>
- 
       <td style="vertical-align: top">       <td style="vertical-align: top">
- 
         <ul>         <ul>
- 
           <li>Module: .module</li>           <li>Module: .module</li>
- 
           <li>Module install: .install</li>           <li>Module install: .install</li>
- 
           <li>Themes:           <li>Themes:
- 
             <ul>             <ul>
- 
               <li>Plain PHP: .theme</li>               <li>Plain PHP: .theme</li>
- 
               <li>PHPTemplate: .tpl.php</li>               <li>PHPTemplate: .tpl.php</li>
- 
               </ul>               </ul>
- 
             </li>             </li>
- 
           <li>Includes: .inc</li>           <li>Includes: .inc</li>
- 
           </ul>           </ul>
- 
         </td>         </td>
- 
       <td style="vertical-align: top">?</td>       <td style="vertical-align: top">?</td>
- 
       <td style="vertical-align: top">       <td style="vertical-align: top">
- 
         <ul>         <ul>
- 
           <li>all files containing PHP code must bear the .php extension</li>           <li>all files containing PHP code must bear the .php extension</li>
- 
           <li>the file containing class Foo must be named Foo.php</td>           <li>the file containing class Foo must be named Foo.php</td>
- 
           </ul>           </ul>
- 
         </td>         </td>
- 
       </tr>       </tr>
- 
     <tr>     <tr>
- 
       <td>Documentation</td>       <td>Documentation</td>
- 
       <td style="vertical-align: top">       <td style="vertical-align: top">
- 
         <ul>         <ul>
- 
           <li>Standard files: LICENSE.txt</li>           <li>Standard files: LICENSE.txt</li>
- 
           <li>Specific files:           <li>Specific files:
- 
             <ul>             <ul>
- 
               <li>CamelCaps.txt</li>               <li>CamelCaps.txt</li>
- 
               <li>Allowed text formats:               <li>Allowed text formats:
- 
                 <ul>                 <ul>
- 
                   <li>txt (UTF8)</li>                   <li>txt (UTF8)</li>
- 
                   <li>PDF</li>                   <li>PDF</li>
- 
                   <li>OpenDocument</li>                   <li>OpenDocument</li>
- 
                   </ul>                   </ul>
- 
                 </li>                 </li>
- 
               <li>Allowed image formats:               <li>Allowed image formats:
- 
                 <ul>                 <ul>
- 
                   <li>SVG, SVGZ</li>                   <li>SVG, SVGZ</li>
- 
                   <li>PNG, including Fireworks</li>                   <li>PNG, including Fireworks</li>
- 
                   <li>JPG</li>                   <li>JPG</li>
- 
                   </ul>                   </ul>
- 
                 </li>                 </li>
- 
               </ul>               </ul>
- 
             </li>             </li>
- 
           </ul>           </ul>
- 
         </td>         </td>
- 
       <td style="vertical-align: top">LICENSE.txt</td>       <td style="vertical-align: top">LICENSE.txt</td>
- 
       <td style="vertical-align: top">?</td>       <td style="vertical-align: top">?</td>
- 
       <td style="vertical-align: top">?</td>       <td style="vertical-align: top">?</td>
- 
       </tr>       </tr>
- 
     </table>     </table>
- 
   </html>   </html>
- 
- 
- 
- 
- 
- 
- 
  
  
 ===== Variables ===== ===== Variables =====
  
- +Variables naming following the rules for functions and methods. Exceptions:
- +
-Variables naming following the rules for functions and methods. +
- +
- +
- +
-Exceptions: +
- +
  
   * existing libraries or APIs are not renamed. Facade APIs may be used until existing libraries match the new format   * existing libraries or APIs are not renamed. Facade APIs may be used until existing libraries match the new format
- 
   * the standard variable $ret should be used for all return values. Always use it to return a value, instead of directly returning the latest instruction result. This helps with a typical debugger configuration: breakpoint on return and $ret as a watched value.   * the standard variable $ret should be used for all return values. Always use it to return a value, instead of directly returning the latest instruction result. This helps with a typical debugger configuration: breakpoint on return and $ret as a watched value.
- 
   * some Hungarian notation is used:    * some Hungarian notation is used: 
- 
     * the name of "unsafe" strings is prefixed by "us_"     * the name of "unsafe" strings is prefixed by "us_"
- 
     * http://www.joelonsoftware.com/articles/Wrong.html     * http://www.joelonsoftware.com/articles/Wrong.html
- 
   * naming resulting from external objects applies the rule by pieces. Example:   * naming resulting from external objects applies the rule by pieces. Example:
- 
     * GTK widgets are named <abbreviated class><Instance> within Glade     * GTK widgets are named <abbreviated class><Instance> within Glade
- 
     * GTK signals are called <signal>     * GTK signals are called <signal>
- 
     * Related callbacks are called on_<abbreviated class><Instance>_<signal>     * Related callbacks are called on_<abbreviated class><Instance>_<signal>
- 
     * Example: on_fmMain_destroy is      * Example: on_fmMain_destroy is 
- 
       * "on_" : the callback for...       * "on_" : the callback for...
- 
       * "fmMain" : a Main Form GtkWindow widget       * "fmMain" : a Main Form GtkWindow widget
- 
       * "_destroy" : the "destroy" GTK signal       * "_destroy" : the "destroy" GTK signal
- 
     * Rationale: forcing CamelCaps for the standard naming convention would result in onFmMainDestroy, which splits ambiguously and is not a default in Glade, and with Fm being capitalized inconsistently in various places in the app. As an instance instead of a class, it should remain lowercase     * Rationale: forcing CamelCaps for the standard naming convention would result in onFmMainDestroy, which splits ambiguously and is not a default in Glade, and with Fm being capitalized inconsistently in various places in the app. As an instance instead of a class, it should remain lowercase
- 
- 
- 
  
  
 ===== Functions and Methods ===== ===== Functions and Methods =====
- 
- 
  
   * Since PHP4 support is not required, visibility (private, protected) settings on class members are recommended when using PHP5 class constructions.   * Since PHP4 support is not required, visibility (private, protected) settings on class members are recommended when using PHP5 class constructions.
- 
   * functions or methods returning unsafe values are prefixed by "us_" just like variables, as "us_someFunctionName()"   * functions or methods returning unsafe values are prefixed by "us_" just like variables, as "us_someFunctionName()"
- 
   * "final" classes should not contain "protected" members, since they can not have derived classes which would take advantage of the "protected" access.   * "final" classes should not contain "protected" members, since they can not have derived classes which would take advantage of the "protected" access.
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
  
  
 ===== Constants ===== ===== Constants =====
- 
- 
  
 As of 01/01/2007, see table above. Note that the PHP builtins "null", "true", and "false" are lowercase, unlike constants from user code. As of 01/01/2007, see table above. Note that the PHP builtins "null", "true", and "false" are lowercase, unlike constants from user code.
- 
- 
  
 Previously, the format was: Previously, the format was:
- 
 <code php> <code php>
- 
 define('G2VERSION', '$Id'); define('G2VERSION', '$Id');
- 
 </code> </code>
- 
- 
  
 This style of coding is now considered obsolete (even under Drupal conventions, the constant should be named G2_VERSION, not G2VERSION), and should be replaced when preparing module versions for Drupal 6 by class constants like G2::VERSION, or more generally Foo::SOME_CONSTANT : This style of coding is now considered obsolete (even under Drupal conventions, the constant should be named G2_VERSION, not G2VERSION), and should be replaced when preparing module versions for Drupal 6 by class constants like G2::VERSION, or more generally Foo::SOME_CONSTANT :
  
 <code php> <code php>
- 
 class G2 class G2
- 
   {   {
- 
   // don't forget the PHPdoc here   // don't forget the PHPdoc here
- 
   const VERSION = '$Id$';   const VERSION = '$Id$';
- 
   }   }
- 
 </code> </code>
- 
  
  
 ===== Drupal-specific: Naming functions and constants within modules ===== ===== Drupal-specific: Naming functions and constants within modules =====
- 
- 
  
   * Drupal mandates some function names, notably, for module "mymodule":   * Drupal mandates some function names, notably, for module "mymodule":
- 
     * default theme functions must be named theme_mymodule_foo      * default theme functions must be named theme_mymodule_foo 
- 
     * hook_foo implementations must be named mymodule_foo     * hook_foo implementations must be named mymodule_foo
- 
   * Beyond that, all other functions in a module should be defined as static public methods of a class named like the module, like:   * Beyond that, all other functions in a module should be defined as static public methods of a class named like the module, like:
- 
 <code php> <code php>
- 
 // don't forget the PHPdoc comments here // don't forget the PHPdoc comments here
- 
 class My_Module class My_Module
- 
   {   {
- 
   // and here   // and here
- 
   const SOME_CONSTANT = 'bar';   const SOME_CONSTANT = 'bar';
- 
- 
  
   // ... and here too   // ... and here too
- 
   static public function foo($op)   static public function foo($op)
- 
     {     {
- 
     // do something and return     // do something and return
- 
     }     }
- 
   }   }
- 
- 
  
 // ..which can be invoked as: // ..which can be invoked as:
- 
 My_Module::foo(My_Module::SOME_CONSTANT); My_Module::foo(My_Module::SOME_CONSTANT);
- 
 </code> </code>
- 
- 
coding.1208469419.txt.gz · Last modified: 2020/11/23 17:23 (external edit)