<?xml version="1.0" encoding="iso-8859-1"?>
<chapter id="coding_conventions">
  <title>moregroupware coding conventions</title>
  
  <para>This is a first step of guidance to a more clear programming. It
    is taken from the PEAR Coding Standards which can be found at
    <ulink url="http://pear.php.net/manual/en/standards.php">http://pear.php.net/manual/en/standards.php
  </ulink>
  .
  These are only excerpts from that to make the main parts clear.
</para>

<section id="coding_conventions_rules_indenting">
  <title>Indenting</title>
  
  <para>Use an indent of 4 spaces, with no tabs.</para>
  
  <para>For UltraEdit 32 (on Windows) Go to Advanced -> Configuration
    and choose the Edit tab.  Check "Use spaces in place of tabs" and
    enter 4 in the next text field which should say something like "Tab
    Stop Value" + an excessive bunch of words.  If you've already written
    code with other tab stops follow the above note and then do Format &gt;
    Tabs to Spaces For hints on other editors go to the URL shown
    above.
  </para>
  
</section>

<section id="coding_conventions_rules_naming">
  <title>Naming conventions</title>
  
  <para>Functions and methods should be named using the "studly caps"
    style (also referred to as "bumpy case" or "camel caps"). Functions
    should in addition have the package name as a prefix, to avoid name
    collisions between packages. The initial letter of the name (after the
    prefix) is lowercase, and each letter that starts a new "word" is
    capitalized. Some examples:
    <programlisting>
      connect()
      getData()
      buildSomeWidget()
      XML_RPC_serializeData()
    </programlisting>
  </para>
  
  <para>Private class members (meaning class members that are intented
    to be used only from within the same class in which they are declared;
    PHP does not yet support truly-enforceable private namespaces) are
    preceeded by a single underscore. For example:
    <programlisting>
      _sort()
      _initTree()
      $this-&gt;_status
    </programlisting>
  </para>
</section>

<section id="coding_conventions_rules_constants">
  <title>Constants</title>
  
  <para>Constants should always be all-uppercase, with underscores to
    seperate words. Prefix constant names with the uppercased name of the
    class/package they are used in. For example, the constants used by the
    DB:: package all begin with "DB_".
  </para>
</section>

<section id="coding_conventions_rules_globals">
  <title>Global variables</title>
  
  <para>If your package needs to define global variables, their name
    should start with a single underscore followed by the package name and
    another underscore. For example, the PEAR package uses a global
    variable called $_PEAR_destructor_object_list.
  </para>
</section>

<section id="coding_conventions_rules_control">
  <title>Control structures</title>
  
  <para>This is a complete if-example:
    <programlisting><![CDATA[
    if ((condition1) || (condition2)) {
        action1;
    } elseif ((condition3) && (condition4)) {
        action2;
    } else {
        defaultaction;
    }]]>
      </programlisting>
      For switch statements: 
      <programlisting><![CDATA[
    switch (condition) {
    case 1:
        action1;
        break;
    case 2:
        action2;
        break;
    default:
        defaultaction;
        break;
    }
]]>
    </programlisting>
  </para>
</section>

<section id="coding_conventions_rules_functions">
  <title>Function calls</title>
  
  <para>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.
  </para>
  
  <para>
    Here's an example: <programlisting>$var = foo($bar, $baz,
      $quux);
    </programlisting>
  </para>
</section>

<section id="coding_conventions_rules_comments">
  <title>Comments</title>
  
  <para>Inline documentation for classes should follow the PHPDoc
    convention, similar to Javadoc.  More information about PHPDoc can be
    found here: <ulink url="http://www.phpdoc.de/">http://www.phpdoc.de/
  </ulink>
  .
  C style comments (/* */) and standard C++ comments (//) are both fine.
  Use of Perl/shell style comments (#) is discouraged.
</para>
</section>

<section id="coding_conventions_rules_inclusions">
<title>Including code</title>

<para>Anywhere you are unconditionally including a class file, use
  require_once().  Anywhere you are conditionally including a class file
  (for example, factory methods), use include_once(). Either of these
  will ensure that class files are included only once.  They share the
  same file list, so you don't need to worry about mixing them - a file
  included with require_once() will not be included again by
  include_once().
</para>
</section>

<section id="coding_conventions_rules_tags">
<title>PHP code tags</title>

<para>Always use &lt;?php ?&gt; to delimit PHP code, not the &lt;?
  ?&gt; shorthand.  This is required for PEAR compliance and is also the
  most portable way to include PHP code on differing operating systems
  and setups.
</para>
</section>

<section id="coding_conventions_rules_cvs">
<title>Using CVS</title>

<para>Include the Id CVS keyword in each file. As each file is edited,
  add this tag if it's not yet present (or replace existing forms such
  as "Last Modified:", etc.).
</para>
</section>

<section id="coding_conventions_rules_additions">
<title>General script structure</title>

<para>Additions to the PEAR conventions:</para>

<programlisting>
  **********
  inclusion:
  **********
  
  global parameters:
  
  $myEnv[module] = "contact";
  $myEnv[output] = "html";
  
  include('MGW_vCard.php');
</programlisting>

<para>(export classes and functions that are to be reused in another
  context to a separate class of file).
</para>

<programlisting>
  ********
  control:
  ********
  
  if (isset($dump)){
  dumpVCard($id, $PHPSESSID);
  } else {
  exportVCard($id, $PHPSESSID);
  }
</programlisting>

<para>(which will be more complex in other modules, but shows at the
  beginning of the page what functions to expect)
</para>

<programlisting>
  ***************
  implementation:
  ***************
  
  function exportVCard($id, $PHPSESSID){
  ...}
  function dumpVCard($id, $PHPSESSID){
  ...}
</programlisting>

<para>Clearly defined interfaces what parameters we need to make the
  function work and to improve testing of single methods).
</para>

</section>

</chapter>
