coding
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
coding [2007/08/17 09:14] – fgm | coding [2020/11/23 17:23] (current) – external edit 127.0.0.1 | ||
---|---|---|---|
Line 1: | Line 1: | ||
+ | ====== Coding conventions - standards for OSInet-originated PHP and HTML code ====== | ||
+ | * OSInet contributions to Drupal | ||
+ | * Contributions to Drupal core follow the [[http:// | ||
+ | * Contributions to non-OSInet contributed code follow the coding convention of said code, usually the same Drupal coding standard as core. | ||
+ | * Contributions outside core follow the here-defined OSInet coding style. | ||
+ | * Contributions to PEAR follow the [[http:// | ||
+ | * Contributions to the Zend Framework follow the [[http:// | ||
+ | |||
+ | The OSInet coding style is mostly the Zend Framework style, except for its indenting rules, which follow the second variant of the [[http:// | ||
+ | |||
+ | Examples on this page are given in the context of a module (Drupal) or class called G2. | ||
+ | |||
+ | All code must work under error_reporting(E_ALL | E_STRICT) | ||
+ | |||
+ | ====== Indenting ====== | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | ===== Function Declarations ===== | ||
+ | |||
+ | < | ||
+ | <table class=" | ||
+ | <tr> | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </tr> | ||
+ | <tr style=" | ||
+ | { | ||
+ | $ret = action; | ||
+ | return $ret; | ||
+ | }</ | ||
+ | return action; | ||
+ | }</ | ||
+ | { | ||
+ | return action; | ||
+ | }</ | ||
+ | </tr> | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | 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: | ||
+ | <code php> | ||
+ | public function someFunctionWithALongName( | ||
+ | $firstParamsHasALongNameToo, | ||
+ | $secondParamIsAlmostWorse | ||
+ | $notForgettingOtherDefaults = 0) | ||
+ | { | ||
+ | $ret = action; | ||
+ | return $ret; | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | ===== Class Declarations ===== | ||
+ | |||
+ | < | ||
+ | <table class=" | ||
+ | <tr> | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </tr> | ||
+ | <tr style=" | ||
+ | { | ||
+ | // members | ||
+ | }</ | ||
+ | { | ||
+ | // members | ||
+ | }</ | ||
+ | </tr> | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | |||
+ | ===== if / then / else ===== | ||
+ | |||
+ | < | ||
+ | <table class=" | ||
+ | <tr> | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </tr> | ||
+ | <tr style=" | ||
+ | { | ||
+ | action1; | ||
+ | } | ||
+ | elseif (test3 && test2) | ||
+ | { | ||
+ | action2; | ||
+ | } | ||
+ | else | ||
+ | { | ||
+ | defaultaction; | ||
+ | }</ | ||
+ | action1; | ||
+ | } | ||
+ | elseif (test3 && test4) { | ||
+ | action2; | ||
+ | } | ||
+ | else { | ||
+ | defaultaction; | ||
+ | }</ | ||
+ | action1; | ||
+ | } elseif ((test3) && (test4)) { | ||
+ | action2; | ||
+ | } else { | ||
+ | defaultaction; | ||
+ | }</ | ||
+ | action1; | ||
+ | } else if (test3) { | ||
+ | | ||
+ | } else { | ||
+ | | ||
+ | }</ | ||
+ | <tr> | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | 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. | ||
+ | |||
+ | |||
+ | ===== switch ===== | ||
+ | |||
+ | < | ||
+ | <table class=" | ||
+ | <tr> | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </tr> | ||
+ | <tr style=" | ||
+ | { | ||
+ | case 1: | ||
+ | action1; | ||
+ | break; | ||
+ | |||
+ | case 2: | ||
+ | action2; | ||
+ | break; | ||
+ | |||
+ | default: | ||
+ | defaultaction; | ||
+ | break; | ||
+ | }</ | ||
+ | case 1: | ||
+ | action1; | ||
+ | break; | ||
+ | |||
+ | case 2: | ||
+ | action2; | ||
+ | break; | ||
+ | |||
+ | default: | ||
+ | defaultaction; | ||
+ | break; | ||
+ | }</ | ||
+ | case 1: | ||
+ | action1; | ||
+ | break; | ||
+ | |||
+ | case 2: | ||
+ | action2; | ||
+ | break; | ||
+ | |||
+ | default: | ||
+ | defaultaction; | ||
+ | break; | ||
+ | }</ | ||
+ | case 1: | ||
+ | break; | ||
+ | |||
+ | case 2: | ||
+ | break; | ||
+ | |||
+ | default: | ||
+ | break; | ||
+ | }</ | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | |||
+ | ===== General table ===== | ||
+ | |||
+ | ^ Category ^ OSInet | ||
+ | ^ Spacing | ||
+ | ^ ... terminal | n.a. ||| ... and a single space after the closing parenthesis. | | ||
+ | ^ Bracing | ||
+ | ^ ... 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. | | ||
+ | ^ ... classes | = ZF | n.a. || The brace is always written on the line underneath the class name. | | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | ====== Function Calls ====== | ||
+ | |||
+ | ^ Category | ||
+ | ^ name to ( | no space |||| | ||
+ | ^ ( to arg1 | no space |||| | ||
+ | ^ arg to , | no space |||| | ||
+ | ^ , to arg | usually 1 space. May vertically align for block-related function calls | 1 space ||| | ||
+ | ^ arg to ) | no space |||| | ||
+ | ^ ) to ; | no space |||| | ||
+ | |||
+ | ZF rules for this are implied by the example in the A.4.5.2 section. | ||
+ | |||
+ | |||
+ | ====== Arrays ====== | ||
+ | |||
+ | Spacing, one-liner: **identical** | ||
+ | Spacing, indented: **Different** | ||
+ | |||
+ | Note that if the line spans longer than 80 characters (often the case with form and menu declarations), | ||
+ | |||
+ | <code php> | ||
+ | $form[' | ||
+ | ( | ||
+ | '# | ||
+ | '# | ||
+ | '# | ||
+ | '# | ||
+ | '# | ||
+ | ); | ||
+ | </ | ||
+ | |||
+ | Additional comma: identical. | ||
+ | |||
+ | ====== Including Code ====== | ||
+ | |||
+ | |||
+ | |||
+ | OSInet contrib code does not support PHP4, so PHP5 structures like the new object model are standard. | ||
+ | |||
+ | |||
+ | |||
+ | 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. | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | ====== File formatting ====== | ||
+ | |||
+ | ^ Feature | ||
+ | | <% %> tags | No | No | ||
+ | | <? ?> tags | No | No | ||
+ | | Closing ?> | No | Should be omitted | ||
+ | | Indenting | ||
+ | | Tabs | No | No | ||
+ | | Line length | as ZF | ||
+ | | Line termination | ||
+ | | __HALT_COMPILER() | unspecified | ||
+ | |||
+ | The rule regarding the closing ?> tag is only applicable to " | ||
+ | |||
+ | |||
+ | ====== Comments, inline doc ====== | ||
+ | |||
+ | < | ||
+ | <table class=" | ||
+ | <tr> | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </tr> | ||
+ | <tr> | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </tr> | ||
+ | <tr> | ||
+ | < | ||
+ | <td style=" | ||
+ | <ul> | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </ul> | ||
+ | </ | ||
+ | <td style=" | ||
+ | < | ||
+ | </ | ||
+ | <td style=" | ||
+ | <td style=" | ||
+ | * Short description for file | ||
+ | * | ||
+ | * Long description for file (if any)... | ||
+ | * | ||
+ | * LICENSE: Some license information | ||
+ | * | ||
+ | * @copyright | ||
+ | * @license | ||
+ | * @version | ||
+ | * @link | ||
+ | * @since | ||
+ | */</ | ||
+ | </tr> | ||
+ | <tr> | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | <td style=" | ||
+ | * Short description for class | ||
+ | * | ||
+ | * Long description for class (if any)... | ||
+ | * | ||
+ | * @copyright | ||
+ | * @license | ||
+ | * @version | ||
+ | * @link | ||
+ | * @since | ||
+ | * @deprecated Class deprecated in Release 2.0.0 | ||
+ | | ||
+ | </tr> | ||
+ | <tr> | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | <td> | ||
+ | <ul> | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </ul> | ||
+ | </td> | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | |||
+ | |||
+ | ====== Using CVS ====== | ||
+ | |||
+ | |||
+ | |||
+ | **Identical** | ||
+ | |||
+ | |||
+ | |||
+ | Additional rule: modules must define a constant containing the version information to be displayed on the module settings page. See the rules for constants below. | ||
+ | |||
+ | |||
+ | |||
+ | ====== Example URLs ====== | ||
+ | |||
+ | |||
+ | |||
+ | **Identical** | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | ====== Naming Conventions ====== | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | ===== General ===== | ||
+ | |||
+ | < | ||
+ | <table class=" | ||
+ | <col span=" | ||
+ | <tr> | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </tr> | ||
+ | <tr style=" | ||
+ | < | ||
+ | < | ||
+ | <td style=" | ||
+ | <td style=" | ||
+ | <td style=" | ||
+ | </tr> | ||
+ | <tr style=" | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </tr> | ||
+ | <tr style=" | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | <td style=" | ||
+ | </tr> | ||
+ | <tr style=" | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </tr> | ||
+ | <tr> | ||
+ | < | ||
+ | <td style=" | ||
+ | { | ||
+ | const SOME_CONSTANT = ' | ||
+ | }</ | ||
+ | <td style=" | ||
+ | <td style=" | ||
+ | <td style=" | ||
+ | const SOME_CONSTANT = ' | ||
+ | }</ | ||
+ | </tr> | ||
+ | <tr> | ||
+ | < | ||
+ | <td style=" | ||
+ | protected _someFieldTwo; | ||
+ | public | ||
+ | <td style=" | ||
+ | <td style=" | ||
+ | <td style=" | ||
+ | protected _someFieldTwo; | ||
+ | public someFieldThree;</ | ||
+ | </tr> | ||
+ | <tr> | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </tr> | ||
+ | <tr> | ||
+ | < | ||
+ | <td style=" | ||
+ | <ul> | ||
+ | < | ||
+ | < | ||
+ | </ul> | ||
+ | </td> | ||
+ | <td style=" | ||
+ | <ul> | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | <ul> | ||
+ | < | ||
+ | < | ||
+ | </ul> | ||
+ | </li> | ||
+ | < | ||
+ | </ul> | ||
+ | </td> | ||
+ | <td style=" | ||
+ | <td style=" | ||
+ | <ul> | ||
+ | < | ||
+ | < | ||
+ | </ul> | ||
+ | </td> | ||
+ | </tr> | ||
+ | <tr> | ||
+ | < | ||
+ | <td style=" | ||
+ | <ul> | ||
+ | < | ||
+ | < | ||
+ | <ul> | ||
+ | < | ||
+ | < | ||
+ | <ul> | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </ul> | ||
+ | </li> | ||
+ | < | ||
+ | <ul> | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </ul> | ||
+ | </li> | ||
+ | </ul> | ||
+ | </li> | ||
+ | </ul> | ||
+ | </td> | ||
+ | <td style=" | ||
+ | <td style=" | ||
+ | <td style=" | ||
+ | </tr> | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | |||
+ | ===== Variables ===== | ||
+ | |||
+ | 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: | ||
+ | * some Hungarian notation is used: | ||
+ | * the name of " | ||
+ | * http:// | ||
+ | * naming resulting from external objects applies the rule by pieces. Example: | ||
+ | * GTK widgets are named < | ||
+ | * GTK signals are called < | ||
+ | * Related callbacks are called on_< | ||
+ | * Example: on_fmMain_destroy is | ||
+ | * " | ||
+ | * " | ||
+ | * " | ||
+ | * Rationale: forcing CamelCaps for the standard naming convention would result in onFmMainDestroy, | ||
+ | |||
+ | |||
+ | ===== 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 " | ||
+ | * " | ||
+ | |||
+ | |||
+ | ===== Constants ===== | ||
+ | |||
+ | As of 01/01/2007, see table above. Note that the PHP builtins " | ||
+ | |||
+ | Previously, the format was: | ||
+ | <code php> | ||
+ | define(' | ||
+ | </ | ||
+ | |||
+ | This style of coding is now considered obsolete (even under Drupal conventions, | ||
+ | |||
+ | <code php> | ||
+ | class G2 | ||
+ | { | ||
+ | // don't forget the PHPdoc here | ||
+ | const VERSION = ' | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | |||
+ | ===== Drupal-specific: | ||
+ | |||
+ | * Drupal mandates some function names, notably, for module " | ||
+ | * 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 = ' | ||
+ | |||
+ | // ... and here too | ||
+ | static public function foo($op) | ||
+ | { | ||
+ | // do something and return | ||
+ | } | ||
+ | } | ||
+ | |||
+ | // ..which can be invoked as: | ||
+ | My_Module:: | ||
+ | </ |
coding.txt · Last modified: 2020/11/23 17:23 by 127.0.0.1