===========================================================================
|| Horde Coding Standards                                                ||
===========================================================================

$Horde: horde/docs/CODING_STANDARDS,v 1.32.2.3 2001/12/24 17:21:54 chuck Exp $

-------------
[1] Indenting
=============

Use an indent of 4 spaces, with no tabs.


----------------------
[2] Control Structures
======================

These include if, for, while, switch, etc. Here is an example if statement,
since it is the most complicated of them:

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

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

In the case of an if with no else clauses, and only a 1 line action,
the curly braces may be omitted:

  if (condition) action;

or:

  if (condition)
      action;

Whichever is more readable under the circumstances is preferred.

For switch statements:

  switch (condition) {
  case 1:
      action1;
      break;

  case 2:
      action2;
      break;

  default:
      defaultaction;
      break;

  } // switch


------------------
[3] 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);

As displayed above, there should be one space on either side of an
equals sign used to assign the return value of a function to a
variable. In the case of a block of related assignments, more space
may be inserted to promote readability:

  $short         = foo($bar);
  $long_variable = foo($baz);


------------------------
[4] Function Definitions
========================

Function declaractions follow the "one true brace" convention:

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

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.


--------------------
[5] Naming Libraries
====================

Libraries (any file located in the 'lib/' directory of the application)
should be named with capital letters at the beginning of each word. Use
studlycaps for naming; a session cache class would be stored in
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.

Example:
The "Example Library" library should be saved as "lib/ExampleLibrary.php".
Any file extending the library/class should be stored in the directory
  "lib/ExampleLibrary/".


------------
[6] Comments
============

Inline documentation for classes should follow the Javadoc convention.  An
overview of the Javadoc standard can be found here:

    http://java.sun.com/products/jdk/javadoc/writingdoccomments/index.html


------------------
[7] 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.

If you are including a static filename, such as a conf file or a template
that is _always_ used, use require.

If you are dynamically including a filename, or want the code to only be
used conditionally (an optional template), use include.


-----------------
[8] PHP Code Tags
=================

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.

However, when embedding echo commands, you should use the shorthand
notation: <?= $name ?> instead of <?php echo $name ?>
This improves the clarity of HTML templates that are scattered with
these constructs.

-------------------------
[9] Header Comment Blocks
=========================

All source code files in the Horde distribution should contain the following
comment block as the header:

Example for LGPL'ed Horde code:

/*
 * $Horde: horde/docs/CODING_STANDARDS,v 1.32.2.3 2001/12/24 17:21:54 chuck Exp $
 *
 * Copyright 1999, 2000, 2001 Original Author <author@example.com>
 * Copyright 2001 Your Name <you@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.
 */

Example for GPL'ed application code:

/*
 * $Horde: horde/docs/CODING_STANDARDS,v 1.32.2.3 2001/12/24 17:21:54 chuck Exp $
 *
 * Copyright 1999, 2000, 2001 Original Author <author@example.com>
 * Copyright 2001 Your Name <you@example.com>
 *
 * See the enclosed file COPYING for license information (GPL).  If you 
 * did not receive this file, see http://www.fsf.org/copyleft/gpl.html.
 */

There's no hard rule to determine when a new code contributer should be
added to the list of authors for a given source file.  In general, their
changes should fall into the "substantial" category (meaning somewhere
around 10% to 20% of code changes).  Exceptions could be made for rewriting
functions or contributing new logic.

Simple code reorganization or bug fixes would not justify the addition of a
new individual to the list of authors.


-------------
[10] 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.


-----------------
[11] Example URLs
=================

Use "example.com" for all example URLs, per RFC 2606.


---------------------
[12] php.ini settings
=====================

All Horde code should work with register_globals = Off. This means using
$HTTP_GET_VARS, $HTTP_POST_VARS, $HTTP_COOKIE_VARS, $HTTP_SESSION_VARS,
$HTTP_SERVER_VARS, and $HTTP_ENV_VARS to access all get, post, cookie,
session, server, and environment data, respectively.

All Horde code should work with error_reporting = E_ALL. Failure to do so would
result in ugly output, error logs getting filled with lots of warning messages,
or even downright broken scripts.

All Horde code should work regardless of the setting of magic_quotes_gpc.
Form data should be passed through Horde::dispelMagicQuotes(), which will
run stripslashes on it if necessary.

No Horde code should assume that '.' is in the include path. Always
specify './' in front of a filename when you are including a file in
the same directory.


-------------------------
[13] XHTML 1.0 Compliance
=========================

All tag names and parameters must be lower case including javascript
event handlers:

    <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, the parameter name is the value.  For example:

    <input type="checkbox" checked="checked">
    <select name="example">
        <option selected="selected" value="1">Example</option>
    </select>
    <td nowrap="nowrap">Example</td>

All tags must be properly closed.  Tags where closing is forbidden must end
with a space and a slash:

    <br />
    <hr />
    <img src="example.gif" alt="Example" />
    <input type="submit" value="Example" />

All form definitions must be on their own line and either fully defined within
a <td></td> pair or be outside table tags. Forms must also aways have an action
parameter:

    <form method="post" action="http://example.com/example.cgi">
    <table>
        <tr><td>example</td></tr>
    </table>
    </from>

    <table>
        <tr><td>
            <form action="javascript:void(0)" onsubmit="return false;">
            </form>
        </td></tr>
    </table>

All JavaScript tags must have a valid language and type parameters:

    <script language="JavaScript" type="text/javascript">
    <!--
    ...
    // -->
    </script>

Nothing may appear after </html>, therefore include any common footers after
all other output.

All images must have an alt parameter:

    <img src="example.gif" alt="<?= _("Example") ?>" />
    <?= Horde::img("example.gif", 'alt="' . _("Example") . '"') ?>

Input field of type "image" does not allow the border parameter, and may render
with a border on some browsers.  Use the following instead:

   <a href="" onclick="document.formname.submit(); return false;"><?= Horde::img("example.gif", 'alt="' . _("Example") . '"' ?></a>


--------------------------------
[14] Database Naming Conventions
================================

All database tables used by Horde resources and Horde applications
need to make sure that their table and field names work in all
databases. Many databases reserve words like 'uid', 'user', etc. for
internal use, and forbid words that are SQL keywords (select, where,
etc.).

A good way to do this for field names is to make the field name
tableName_fieldName.

Other general guidelines: Table names should be singular (Users);
field names should be singular (user_Name).


---------------------------
[15] Regular Expression Use
===========================

Always use the preg_* functions if possible 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_*.

NEVER use a regular expression to match or replace a static string.
explode() (in place of split()), str_replace(), strstr(), or strtr()
do the job much more efficiently.
