Difference between revisions of "Programming Style"

From GeeklogWiki
Jump to: navigation, search
(=Naming Convention:=)
(Including Code and lib-common.php)
 
(10 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
Good coding style makes your code more easily readable, fixable and modifiable by other people. It is strongly encouraged. It is a goal to which we all strive and seldom reach. We encourage you to practice good coding style. At the very least, correctly indent your code.  
 
Good coding style makes your code more easily readable, fixable and modifiable by other people. It is strongly encouraged. It is a goal to which we all strive and seldom reach. We encourage you to practice good coding style. At the very least, correctly indent your code.  
  
The following coding style suggestions are mostly adapted from the PHP Pear project. You should see that documentation for examples if you have any questions. It can be found at http://pear.php.net/manual/en/standards.php.  
+
The following coding style suggestions are mostly adapted from the PHP [http://pear.php.net/ PEAR] project. The PEAR coding style has also been adopted as the official Geeklog [[Coding Guidelines]].
  
  
 +
== Naming Convention ==
  
== Naming Convention: ==
+
Choose a short prefix for all your global functions and variables. This makes it easy to determine where a particular function or variable came from. It also prevents naming collisions which are difficult to debug. Note that Geeklog itself follows this convention, e.g. all functions from <tt>lib-common.php</tt> start with <code>COM_</code>. In the Contact plugin the prefix CT_ was used. It can also help to prefix all global variables with an underscore, so global variables in the Contact plugin start with <code>$_CT_</code>.
  
Choose a short prefix for all your global functions and variables. This makes it easy to determine where a particular function or variable came from. It also prevents naming collisions which are difficult to debug. Note that Geeklog itself follows this convention, e.g. all functions from lib-common.php start with COM_. In the Contact plugin the prefix CT_ was used. It can also help to prefix all global variables with an underscore, so global variables in the Contact plugin start with $_CT_.  
+
Geeklog uses this convention of any underscore and capital letters to indicate a global variable e.g. <code>$_TABLES</code>, <code>$_CONF</code>, <code>$_USER</code> variables.
  
Geeklog uses this convention of any underscore and capital letters to indicate a global variable e.g. $_TABLES, $_CONF, $_USER variables.
 
  
== Indenting: ==
+
== Indenting ==
  
 
Use an indent of 4 spaces, with no tabs. Please indent your code.  
 
Use an indent of 4 spaces, with no tabs. Please indent your code.  
  
  
== Control Structures: ==
+
== Control Structures ==
  
 
Control statements should have one space between the control keyword and opening parenthesis, to distinguish them from function calls. For example:  
 
Control statements should have one space between the control keyword and opening parenthesis, to distinguish them from function calls. For example:  
 +
 +
<pre>
 
if ((condition1) || (condition2)) {     
 
if ((condition1) || (condition2)) {     
 
     action1;
 
     action1;
Line 26: Line 28:
 
     defaultaction;
 
     defaultaction;
 
}
 
}
 +
</pre>
  
  
 
+
== Function Calls ==
== Function Calls: ==
 
  
 
Functions should be called with no spaces between the function name, the opening parenthesis, and the first parameter, spaces between commas and each parameter, and no space between the last parameter, the closing parenthesis, and the semicolon. Here's an example:  
 
Functions should be called with no spaces between the function name, the opening parenthesis, and the first parameter, spaces between commas and each parameter, and no space between the last parameter, the closing parenthesis, and the semicolon. Here's an example:  
$var = foo($bar, $baz, $quux);
 
  
 +
<pre>$var = foo($bar, $baz, $quux);</pre>
  
  
== Function Declarations: ==
+
== Function Declarations ==
  
 
Function declarations follow the "one true brace" convention:  
 
Function declarations follow the "one true brace" convention:  
 +
<pre>
 
function fooFunction($arg1, $arg2 = '')
 
function fooFunction($arg1, $arg2 = '')
 
{     
 
{     
Line 46: Line 49:
 
     return $val;
 
     return $val;
 
}
 
}
 +
</pre>
  
  
 +
== Comments ==
  
== Comments: ==
+
Inline documentation for classes should follow the [http://phpdoc.org/ phpDocumentor] convention, which is similar to Javadoc. Also see [[Source Code Documentation]].
  
Inline documentation for classes should follow the PHPDoc convention, similar to Javadoc. More information about PHPDoc can be found here: http://phpdocu.sourceforge.net/. Note: the documentation files for lib-common.php and lib-security.php were generated directly from the source files by PHPDocu.  
+
Note: the documentation files for [http://project.geeklog.net/src/Geeklog/_public_html---lib-common.php.html lib-common.php] and [http://project.geeklog.net/src/Geeklog/_system---lib-security.php.html lib-security.php] were generated directly from the source files by phpDocumentor.
  
  
 +
== Including Code ==
  
== Including Code: ==
+
Anywhere you are unconditionally including a class or library file, use <code>require_once</code>. Anywhere you are conditionally including a class or library file, use <code>include_once</code>.
  
Anywhere you are unconditionally including a class or library file, use require_once(). Anywhere you are conditionally including a class or library file, use include_once().
+
Additionally it is recommended that all of your project includes use the fully qualified path to the include file instead of assuming the user has the current directory in the search path. Many PHP installations don't include the current directory in the path and statements such as <code>include 'myfunctions.php'</code> will fail. Use the <code>$_CONF['path_html']</code> variable in the include statement.
Additionally it is recommended that all of your project includes use the fully qualified path to the include file instead of assuming the user has the current directory in the seach path. Many PHP implementations don't include the current directory in the path and statements such as include('myfunctions.php') will fail. Use the $_CONF['path_html'] variable in the include statement. Example:
 
  
include($_CONF['path_html'] . "/myblock/mb_functions.php");
+
'''Example:'''
 
  
 +
<pre>require_once '../lib-common.php';
 +
include $_CONF['path_html'] . '/myblock/mb_functions.php';</pre>
  
 +
Please note that <code>$_CONF['path_html']</code> is only available after you have [[Including lib-common.php|included <tt>lib-common.php</tt>]].
  
  
== PHP Code Tags: ==
+
== PHP Code Tags ==
  
 
Always use <?php ?> to delimit PHP code, not the <? ?> shorthand.
 
Always use <?php ?> to delimit PHP code, not the <? ?> shorthand.
 +
 +
 +
[[Category:Plugin Developers Handbook]] [[Category:Plugin Development]]

Latest revision as of 17:53, 21 May 2009

Good coding style makes your code more easily readable, fixable and modifiable by other people. It is strongly encouraged. It is a goal to which we all strive and seldom reach. We encourage you to practice good coding style. At the very least, correctly indent your code.

The following coding style suggestions are mostly adapted from the PHP PEAR project. The PEAR coding style has also been adopted as the official Geeklog Coding Guidelines.


Naming Convention

Choose a short prefix for all your global functions and variables. This makes it easy to determine where a particular function or variable came from. It also prevents naming collisions which are difficult to debug. Note that Geeklog itself follows this convention, e.g. all functions from lib-common.php start with COM_. In the Contact plugin the prefix CT_ was used. It can also help to prefix all global variables with an underscore, so global variables in the Contact plugin start with $_CT_.

Geeklog uses this convention of any underscore and capital letters to indicate a global variable e.g. $_TABLES, $_CONF, $_USER variables.


Indenting

Use an indent of 4 spaces, with no tabs. Please indent your code.


Control Structures

Control statements should have one space between the control keyword and opening parenthesis, to distinguish them from function calls. For example:

if ((condition1) || (condition2)) {    
    action1;
} elseif ((condition3) && (condition4)) { 
    action2;
} else {    
    defaultaction;
}


Function Calls

Functions should be called with no spaces between the function name, the opening parenthesis, and the first parameter, spaces between commas and each parameter, and no space between the last parameter, the closing parenthesis, and the semicolon. Here's an example:

$var = foo($bar, $baz, $quux);


Function Declarations

Function declarations follow the "one true brace" convention:

function fooFunction($arg1, $arg2 = '')
{    
    if (condition) {
        statement;    
    }    
    return $val;
}


Comments

Inline documentation for classes should follow the phpDocumentor convention, which is similar to Javadoc. Also see Source Code Documentation.

Note: the documentation files for lib-common.php and lib-security.php were generated directly from the source files by phpDocumentor.


Including Code

Anywhere you are unconditionally including a class or library file, use require_once. Anywhere you are conditionally including a class or library file, use include_once.

Additionally it is recommended that all of your project includes use the fully qualified path to the include file instead of assuming the user has the current directory in the search path. Many PHP installations don't include the current directory in the path and statements such as include 'myfunctions.php' will fail. Use the $_CONF['path_html'] variable in the include statement.

Example:

require_once '../lib-common.php';
include $_CONF['path_html'] . '/myblock/mb_functions.php';

Please note that $_CONF['path_html'] is only available after you have included lib-common.php.


PHP Code Tags

Always use <?php ?> to delimit PHP code, not the <? ?> shorthand.