Differences

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

--- coding [2008/04/17 22:02] – fgm
+++ coding [2020/11/23 17:23] (current) – external edit 127.0.0.1
@@ Line 45: / Line 45: @@
     <th>ZF</th>
     </tr>
-  <tr style="white-space: pre; font-family: monospace;">
+  <tr style="white-space: pre; font-family: monospace;"><td style="vertical-align: top">private function foo($bar, $baz = 'qux')
-    <td style="vertical-align: top">private function foo($bar, $baz = 'qux')
   {
   $ret = action;
   return $ret;
-  }</td>
+  }</td><td style="vertical-align: top">function _g2_foo($bar, $baz = 'qux') {
-    <td style="vertical-align: top">function _g2_foo($bar, $baz = 'qux') {
   return action;
-}</td>
+}</td><td colspan="2" style="vertical-align: top">private function foo($bar, $baz = 'qux')
-      <td colspan="2" style="vertical-align: top">private function foo($bar, $baz = 'qux')
     {
         return action;
@@ Line 89: / Line 86: @@
     <th>ZF</th>
     </tr>
-  <tr style="white-space: pre; font-family: monospace;">
+  <tr style="white-space: pre; font-family: monospace;"><td style="vertical-align: top">class Foo
-    <td style="vertical-align: top">class Foo
   {
   // members
-  }</td>
+  }</td><td style="vertical-align: top">N.A: no classes</td><td>?</td><td style="vertical-align: top">class Foo
-    <td style="vertical-align: top">N.A: no classes</td>
-      <td>?</td>
-    <td style="vertical-align: top">class Foo
 {
     // members
@@ Line 115: / Line 108: @@
     <th>ZF</th>
     </tr>
-  <tr style="white-space: pre; font-family: monospace;">
+  <tr style="white-space: pre; font-family: monospace;"><td style="vertical-align: top">if (test1 || test2)
-    <td style="vertical-align: top">if (test1 || test2)
   {
   action1;
@@ Line 127: / Line 119: @@
   {
   defaultaction;
-  }</td>
+  }</td><td style="vertical-align: top">if (test1 || test2) {
-    <td style="vertical-align: top">if (test1 || test2) {
   action1;
 }
@@ Line 136: / Line 127: @@
 else {
   defaultaction;
-}</td>
+}</td><td style="vertical-align: top">if ((test1) || (test2)) {
-    <td style="vertical-align: top">if ((test1) || (test2)) {
     action1;
 } elseif ((test3) && (test4)) {
@@ Line 143: / Line 133: @@
 } else {
     defaultaction;
-}</td>
+}</td><td style="vertical-align: top">if (test1) {
-    <td style="vertical-align: top">if (test1) {
     action1;
 } else if (test3) {
@@ Line 150: / Line 139: @@
 } else {
    defaultaction;
-}</td>
+}</td></tr>
-    </tr>
   <tr>
     <td>&nbsp;</td>
@@ Line 175: / Line 163: @@
     <th>ZF</th>
     </tr>
-    <tr style="white-space: pre; font-family: monospace">
+    <tr style="white-space: pre; font-family: monospace"><td style="vertical-align: top">switch (condition)
-      <td style="vertical-align: top">switch (condition)
   {
   case 1:
@@ Line 189: / Line 176: @@
     defaultaction;
     break;
-  }</td>
+  }</td><td style="vertical-align: top">switch (condition) {
-      <td style="vertical-align: top">switch (condition) {
   case 1:
     action1;
@@ Line 202: / Line 188: @@
     defaultaction;
     break;
-}</td>
+}</td><td style="vertical-align: top">switch (condition) {
-      <td style="vertical-align: top">switch (condition) {
 case 1:
     action1;
@@ Line 215: / Line 200: @@
     defaultaction;
     break;
-}</td>
+}</td><td style="vertical-align: top">switch (condition) {
-      <td style="vertical-align: top">switch (condition) {
     case 1:
         break;
@@ Line 225: / Line 209: @@
     default:
         break;
-}</td>
+}</td></tr>
-    </tr>
   </table>
 </html>
@@ Line 321: / Line 304: @@
 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 ======
 <html>
   <table class="inline">
     <tr>
       <th>Category</th>
       <th>OSInet</th>
       <th>Drupal</th>
       <th>PEAR</th>
       <th>ZF</th>
       </tr>
     <tr>
       <td>Documentation format</td>
       <td>PHPDocumentor</td>
       <td>Doxygen</td>
       <td>?</td>
       <td>PHPDocumentor</td>
       </tr>
     <tr>
       <td>File header</td>
       <td style="vertical-align: top; text-alignment: left; font-family: monospace">like ZF, but
         <ul>
           <li>use CeCill 2.0 license if possible</li>
           <li>@package and @subpackage tags to group files</li>
           <li>see tag to cross-refer elements</li>
           <li>@version tag can use other VCS' equivalents to CVS' $Id$
           </ul>
        </td>
       <td style="vertical-align: top; text-alignment: left; font-family: monospace">
         <pre>// $Id$
         </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">/**
  * Short description for file
  *
  * Long description for file (if any)...
  *
  * LICENSE: Some license information
  *
  * @copyright  2005 Zend Technologies
  * @license    http://www.zend.com/license/3_0.txt   PHP License 3.0
  * @version    CVS: $Id:$
  * @link       http://dev.zend.com/package/PackageName
  * @since      File available since Release 1.2.0
 */</td>
       </tr>
     <tr>
       <td>File header for class file</td>
       <td>as ZF, except @version, use $Id$</td>
       <td>N.A.: no classes</td>
       <td>?</td>
       <td style="vertical-align: top; text-alignment: left; white-space: pre; font-family: monospace">/**
  * Short description for class
  *
  * Long description for class (if any)...
  *
  * @copyright  2005 Zend Technologies
  * @license    http://www.zend.com/license/3_0.txt   PHP License 3.0
  * @version    Release: @package_version@
  * @link       http://dev.zend.com/package/PackageName
  * @since      Class available since Release 1.2.0
  * @deprecated Class deprecated in Release 2.0.0
  */</td>
       </tr>
     <tr>
       <td>Function header</td>
       <td>as ZF</td>
       <td>unspecified</td>
       <td>?</td>
       <td>
         <ul>
           <li>Textual description</li>
           <li>all @param</li>
           <li>@return</li>
           <li>@throws if the function throws an exception</li>
           <li>@access now obsoleted by visibility attributes</li>
           </ul>
         </td>
     </table>
   </html>
@@ Line 511: / Line 412: @@
 ====== Naming Conventions ======
@@ Line 533: / Line 436: @@
 <html>
   <table class="inline" style="width: 100%">
     <col span="5" align="left" />
     <tr>
       <th>Element</th>
       <th>OSInet</th>
       <th>Drupal</th>
       <th>PEAR</th>
       <th>ZF</th>
       </tr>
     <tr style="vertical-align: top">
       <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">?</td>
       <td style="font-family: monospace">getElementById()</td>
       </tr>
     <tr style="vertical-align: top">
       <td>Function scope</td>
       <td>as ZF</td>
       <td>No classes, so use "&lt;module_name&gt;_" as a namespace to avoid name collision</td>
       <td>?</td>
       <td>Floating functions are discouraged. Use a static class.</td>
       </tr>
     <tr style="vertical-align: top">
       <td>Accessors</td>
       <td>as ZF</td>
       <td>N.A.: no classes</td>
       <td>?</td>
       <td style="font-family: monospace">getSomeField<br />setSomeField</td>
       </tr>
     <tr style="vertical-align: top">
       <td>Design patterns</td>
       <td>as ZF</td>
       <td>unspecified</td>
       <td>?</td>
       <td>Include name of pattern in the name of the method, where practical</td>
       </tr>
     <tr>
       <td>Constants</td>
       <td style="white-space: pre; font-family: monospace; vertical-align: top">class G2
   {
   const 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">class G2 {
   const SOME_CONSTANT = 'foo';
 }</td>
       </tr>
     <tr>
       <td>Class fields</td>
       <td style="white-space: pre; font-family: monospace; vertical-align: top">private   _someFieldOne;
 protected _someFieldTwo;
 public    someFieldThree;</td>
       <td style="vertical-align: top">PHP4 pseudo-private field: _some_field</td>
       <td style="vertical-align: top">?</td>
       <td style="white-space: pre; font-family: monospace; vertical-align: top">private _someFieldOne;
 protected _someFieldTwo;
 public someFieldThree;</td>
       </tr>
     <tr>
       <td>Global variables</td>
       <td>no specific rule</td>
       <td>_g2_some_variable</td>
       <td>?</td>
       <td>no specific rule</td>
       </tr>
     <tr>
       <td>Code files</td>
       <td style="vertical-align: top">
         <ul>
           <li>Drupal components: as Drupal</li>
           <li>elsewhere: as ZF</li>
           </ul>
         </td>
       <td style="vertical-align: top">
         <ul>
           <li>Module: .module</li>
           <li>Module install: .install</li>
           <li>Themes:
             <ul>
               <li>Plain PHP: .theme</li>
               <li>PHPTemplate: .tpl.php</li>
               </ul>
             </li>
           <li>Includes: .inc</li>
           </ul>
         </td>
       <td style="vertical-align: top">?</td>
       <td style="vertical-align: top">
         <ul>
           <li>all files containing PHP code must bear the .php extension</li>
           <li>the file containing class Foo must be named Foo.php</td>
           </ul>
         </td>
       </tr>
     <tr>
       <td>Documentation</td>
       <td style="vertical-align: top">
         <ul>
           <li>Standard files: LICENSE.txt</li>
           <li>Specific files:
             <ul>
               <li>CamelCaps.txt</li>
               <li>Allowed text formats:
                 <ul>
                   <li>txt (UTF8)</li>
                   <li>PDF</li>
                   <li>OpenDocument</li>
                   </ul>
                 </li>
               <li>Allowed image formats:
                 <ul>
                   <li>SVG, SVGZ</li>
                   <li>PNG, including Fireworks</li>
                   <li>JPG</li>
                   </ul>
                 </li>
               </ul>
             </li>
           </ul>
         </td>
       <td style="vertical-align: top">LICENSE.txt</td>
       <td style="vertical-align: top">?</td>
       <td style="vertical-align: top">?</td>
       </tr>
     </table>
   </html>
 ===== 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
   * 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:
     * the name of "unsafe" strings is prefixed by "us_"
     * http://www.joelonsoftware.com/articles/Wrong.html
   * naming resulting from external objects applies the rule by pieces. Example:
     * GTK widgets are named <abbreviated class><Instance> within Glade
     * GTK signals are called <signal>
     * Related callbacks are called on_<abbreviated class><Instance>_<signal>
     * Example: on_fmMain_destroy is
       * "on_" : the callback for...
       * "fmMain" : a Main Form GtkWindow widget
       * "_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
 ===== Functions and Methods =====
   * 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()"
   * "final" classes should not contain "protected" members, since they can not have derived classes which would take advantage of the "protected" access.
 ===== 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.
 Previously, the format was:
 <code php>
 define('G2VERSION', '$Id');
 </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 :
 <code php>
 class G2
   {
   // don't forget the PHPdoc here
   const VERSION = '$Id$';
   }
 </code>
 ===== Drupal-specific: Naming functions and constants within modules =====
   * Drupal mandates some function names, notably, for module "mymodule":
     * default theme functions must be named theme_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:
 <code php>
 // don't forget the PHPdoc comments here
 class My_Module
   {
   // and here
   const SOME_CONSTANT = 'bar';
   // ... and here too
   static public function foo($op)
     {
     // do something and return
     }
   }
 // ..which can be invoked as:
 My_Module::foo(My_Module::SOME_CONSTANT);
 </code>