[cvs] [Wiki] changed: Horde4/CodingStandards
Chuck Hagenbuch
chuck at horde.org
Wed Dec 31 19:02:14 UTC 2008
chuck Wed, 31 Dec 2008 14:02:14 -0500
Modified page: http://wiki.horde.org/Horde4/CodingStandards
New Revision: 1.1
Change log: first pass of updates for Horde 4. much more needed
@@ -28,9 +28,12 @@
Language Case
=============
When working with PHP statements, constructs or keywords, lowercase text is
-required.
+required. This does not apply to classes provided by PHP, which should be
+written as they are in the PHP manual (e.g.
`DOMDocument::createCDATASection`_)
+
+.. _DOMDocument::createCDATASection:
http://us.php.net/manual/en/domdocument.createcdatasection.php
Control Structures
==================
@@ -126,30 +129,33 @@
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.
-Functions used only in the current script/class (e.g. private member methods)
+Functions used only in the current script/class (e.g. private or
protected methods)
should begin with a ``_`` character (e.g. ``_exampleLibrary``). This helps
distinguish these private function calls from other, public function calls.
Class Definitions
=================
-Class definitions follow the "K&R/Kernel" convention::
-
- class Some_Class {
+Class definitions also follow the "BSD/Allman" convention::
+ class Some_Class
+ {
+ /**
+ *
+ */
var $_variable;
- function fooFunction()
+ public function fooFunction()
{
statement;
}
}
-Note the blank lines at the beginning and end of the class definition.
+Note the blank line at the end of the class definition.
Naming Libraries
================
@@ -160,10 +166,9 @@
``lib/SessionCache.php``.
If the library/class is extended, the extending files should be stored in a
directory under ``lib/`` with the same name as the original library.
-Subclasses follow the exact same naming requirements, except that if the
-subclass is instantiated by a factory method, it should be all lowercase.
+Subclasses follow the exact same naming requirements.
Example
-------
@@ -174,11 +179,11 @@
Comments
========
-Inline documentation for classes should follow the `Javadoc convention`_.
+Inline documentation for classes should follow the `phpDocumentor
conventions`_.
-.. _Javadoc convention:
http://java.sun.com/products/jdk/javadoc/writingdoccomments/index.html
+.. _phpDocumentor conventions: http://phpdoc.org/
Quick example for private variable definition for Horde::
/**
@@ -190,11 +195,8 @@
Quick example function definition for Horde::
/**
* The description of the function goes here.
- *
- * @access [private | protected]
- * [Don't bother with "public" since it is the default if not specified.]
*
* @param datatype $variablename Description of variable.
* @param datatype $variable2name Description of variable2.
* ...
@@ -203,10 +205,8 @@
*
* @return datatype Description of return value.
* [Once again, insert 2 spaces after the datatype, and line up all
* subsequent lines, if any, with this character.]
- *
- * @abstract [Only if necessary]
*
* @since Horde x.x [Only if necessary - use if function is added to the
* current release versions to indicate that the function has not been
* available in previous versions.]
@@ -215,36 +215,31 @@
Including Code
==============
-If you are including a class, function library, or anything else which would
-cause a parse error if included twice, always use `include_once`_. This will
-ensure that no matter how many factory methods we use or how much dynamic
-inclusion we do, the library will only be included once.
+You should not explicitly include or require classes. Horde provides an
+cause a parse error if included twice, the class should be autoloaded. This
+will allow maximum flexibility in managing class libraries
-If you are including a static filename, such as a conf file or a
template that
-is *always* used, use `require`_.
+For all other includes (configuration files, data files, etc.) use
`include`_.
-If you are dynamically including a filename, or want the code to only be used
-conditionally (an optional template), use `include`_.
-
-.. _include_once: http://www.php.net/manual/en/function.include-once.php
-.. _require: http://www.php.net/manual/en/function.require.php
-.. _include: http://www.php.net/manual/en/function.include.php
+.. _autoload: http://php.net/autoload
+.. _include: http://php.net/include
PHP Code Tags
=============
-Always use ``<?php ?>`` to delimit PHP code, not the ``<? ?>`` shorthand.
+Always use ``<?php`` to delimit PHP code, not the ``<?`` shorthand.
This is required for PEAR compliance and is also the most portable way to
include PHP code on differing operating systems and setups.
In templates, make sure to use this as well (``<?php echo $varname ?>``), as
the shortcut version (``<?= $var ?>``) does not work with `short_open_tag`_
turned off.
-In library files, there is no need to have the closing '?>'.
+Files should never end with a closing closing '?>'. This is redundant and can
+allow whitespace added to the end of a file to cause PHP to send
headers early.
.. _short_open_tag:
http://www.php.net/manual/en/configuration.directives.php#ini.short-open-tag
@@ -258,21 +253,20 @@
/**
* The Horde_Foo:: class provides an API for various foo
* techniques that can be used by Horde applications.
- *
- * $Horde
*
* Copyright 1999-2001 Original Author <author at example.com>
* Copyright 2001 Your Name <you at example.com>
*
* See the enclosed file COPYING for license information (LGPL). If you
* did not receive this file, see http://www.fsf.org/copyleft/lgpl.html.
*
- * @author Original Author <author at example.com>
- * @author Your Name <you at example.com>
- * @since Horde 3.0
- * @package Horde_Package
+ * @author Original Author <author at example.com>
+ * @author Your Name <you at example.com>
+ * @since Horde 3.0
+ * @category Horde
+ * @package Horde_Package
*/
.. _LGPL: http://www.opensource.org/licenses/lgpl-license.php
@@ -289,12 +283,13 @@
*
* See the enclosed file COPYING for license information (GPL). If you
* did not receive this file, see http://www.fsf.org/copyleft/gpl.html.
*
- * @author Original Author <author at example.com>
- * @author Your Name <you at example.com>
- * @since App 1.0
- * @package app
+ * @author Original Author <author at example.com>
+ * @author Your Name <you at example.com>
+ * @since App 1.0
+ * @category Horde
+ * @package app
*/
.. _GPL: http://www.opensource.org/licenses/gpl-license.php
@@ -306,18 +301,8 @@
contributing new logic.
Simple code reorganization or bug fixes would not justify the addition of a
new individual to the list of authors.
-
-
-CVS Tags
-========
-
-Include the <dollar>Horde: <dollar> CVS vendor tag in each file. As
each file
-is edited, add this tag if it's not yet present (or replace existing forms
-such as <dollar>Id<dollar>, "Last Modified:", etc.).
-
-EXCEPTION: Don't include these in templates.
Example URLs
============
@@ -370,9 +355,9 @@
All tag names and parameters must be lower case including javascript event
handlers::
- <font color="#FFFFFF">...</font>
+ <font color="#ffffff">...</font>
<a href="http://example.com" onmouseover="status=''"
onmouseout="status=''">...</a>
All tag parameters must be of a valid parameter="value" form (numeric values
must also be surrounded by quotes). For parameters that had no
value in HTML,
@@ -411,11 +396,9 @@
All JavaScript tags must have a valid type parameter::
<script type="text/javascript">
- <!--
...
- // -->
</script>
Nothing may appear after ``</html>``, therefore include any common footers
after all other output.
@@ -462,11 +445,11 @@
Regular Expression Use
======================
-Always use the `preg_`_ functions if possible instead of `ereg_`_ (and
+Always use the `preg_`_ functions instead of `ereg_`_ (and
`preg_split()`_ instead of `split()`_); they are included in PHP by default
-and much more efficient and much faster than `ereg_`_.
+and faster than `ereg_`_; `ereg_`_ is also deprecated in PHP 5.3+.
**NEVER** use a regular expression to match or replace a static string.
`explode()`_ (in place of `split()`_), `str_replace()`_, `strpos()`_, or
`strtr()`_ do the job much more efficiently.
@@ -490,14 +473,9 @@
Parameter Passing
=================
-Objects should be passed by reference. Everything else, including arrays,
-should be passed by value wherever semantically possible.
-
-[Zend Engine 2: objects should also be passed by value as the engine
takes care
-of using references for objects]
-
+Parameters should be passed by value wherever semantically possible.
This practice takes full advantage of reference counting.
.. Note:: The `ternary operator`_ automatically returns a copy of
its operands,
so don't use it with objects unless you are sure you want
to return an
@@ -537,9 +515,9 @@
Private Variables
=================
Variables used exclusively within a class should begin with a
underscore ('_')
-character. An example class variable definition: ``var $_variablename;``
+character. An example class variable definition: ``protected
$_variablename;``
Array Definitions
=================
@@ -551,9 +529,9 @@
'name1' => 'value1',
'name2' => array(
'subname1' => 'subvalue1',
'subname2' => 'subvalue2'
- )
+ ),
);
The only exception should be for empty or short arrays that fit on one line,
which may be written as::
@@ -726,9 +704,9 @@
define()
========
-Surprisingly enough, `define()`_ is a somewhat slow function in PHP
(as of PHP
+`define()`_ is a somewhat slow function in PHP (as of PHP
4.3.x) so excessive use is discouraged.
Using `define()`_ in classes should be OK - we will sacrifice a tiny bit of
speed for readability of code. `define()`_ should NOT be used for
actionIDs -
@@ -847,9 +825,9 @@
Disk I/O
--------
Disk read and write operations are slow. If possible read and write files in
-large chunks. According to PHP documentation, file_get_contents() is
+large chunks. According to the PHP documentation, file_get_contents() is
potentially much faster than using fopen()/fread()/fclose().
STDIN/STDOUT/STDERR
More information about the cvs
mailing list