<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
  "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
  <!ENTITY % cartoweb SYSTEM "../cartoweb.ent" >
  %cartoweb;
  <!ENTITY % user SYSTEM "../user/user.ent" >
  %user;
]>

<!-- $Id: code_convention.xml,v 1.9 2007-07-26 15:15:12 olivier Exp $ -->

<chapter id="dev.code_convention">
 <title>Code Convention</title>

 <sect1 id="dev.code_convention.intro"> 
  <title>Introduction</title>
  <para>
   As an Open-Source software, &cartoweb; needs to be written following some
   coding guidelines and/or rules. It is the required condition unless the
   developpers community isn't able to share new features and enhancements.
  </para>
  <para>
   Some of those advises may seem obvious, others less. For all, it is principaly
   a good way to produce more readable, maintainable and portable code.
  </para>
 </sect1>
 <sect1 id="dev.code_convention.general"> 
  <title>General Coding Rules</title>
  <sect2 id="dev.code_convention.general.paths">
   <title>Paths</title>
   <para>
    It is highly recommended to be avoid absolute paths as much as possible.
    &cartoclient; and &cartoserver; may be relocated with very minimal even none reconfiguration.
   </para>
  </sect2>
  <sect2 id="dev.code_convention.general.extract">
   <title>Extract and Run Deployement</title>
   <para>
    It should be possible to extract the archive, launch a script,
    edit few options, and be ready to use the application with
    the built-in data set (see test mapfile).
   </para>
  </sect2>
  <sect2 id ="dev.code_convertion.general.config">
   <title>Development Configuration</title>
   <para>
    Developers should absolutely set the following variables to true in their config
    (on both client and server sides):
     <warning>
        <para>
          &profile_overriden_plural_nowarning;
        </para>
     </warning>
    <itemizedlist>
     <listitem><para>showDevelMessages = true</para></listitem>
     <listitem><para>developerIniConfig = true</para></listitem>
    </itemizedlist>
   </para>
  </sect2>
  <sect2 id="dev.code_convention.general.unitTests">
   <title>Unit Tests</title>
   <para>
    Code should produce no notices before any CVS commit. Code should pass all tests.
   </para>
   <para>
    This also means that the developpers should add and run unit tests for every new
    feature they add.
   </para>
   <para>
    See <xref linkend="dev.unit_test" />.
   </para>
  </sect2>
 </sect1>
 <sect1 id="dev.code_convention.php">
  <title>PHP</title>
  <sect2 id="dev.code_convertion.php.style">
   <title>Coding Style</title>
   <para>
    Developers should use the PEAR coding standards as the coding style reference
    in &cartoweb;, with some exceptions. Have a look at
    <ulink url="http://pear.php.net/manual/en/standards.php" />.
   </para>
   <para>
    Following are briefly described some guidelines to respect.
   </para>
   <sect3 id="dev.code_convention.php.style.indent"> 
    <title>Indent</title>
    <para>
     Developers should respect some indentation conventions when writing PHP code
     in &cartoweb;:
     <itemizedlist>
      <listitem>
       <para>
       4 spaces indentations are recommended,
       </para>
      </listitem>
      <listitem>
       <para>
       the use of tabs for indentation is prohibited, use space instead
       (select the appropriate preferences in your favorite code editor if needed).
       </para>
      </listitem>
     </itemizedlist>
    </para>
   </sect3>
   <sect3 id="dev.code_convention.php.style.control">
    <title>Control Structures</title>
    <para>
     Control statements should have one space between the control keyword
     and opening parenthesis.
    </para>
    <para>
     It is also recommended to use curly braces even when they are optional.
    </para>
    <para>This is correct:</para>
     <programlisting><![CDATA[if (condition) {
  ...
}]]></programlisting>
   </sect3> 
   <sect3 id="dev.code_convention.php.style.functioncalls">
    <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>This is correct:</para>
     <programlisting><![CDATA[$var = foo($bar, $baz, $quux);
]]></programlisting>
   </sect3>
   <sect3 id="dev.code_convention.php.style.functiondefs">
    <title>Function Definitions</title>
    <para>
     Function declarations follow the "one true brace" convention.
    </para>
    <para>
     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.
    </para>
   </sect3> 
   <sect3 id="dev.code_convention.php.style.modifiers">
    <title>Class Modifiers</title>
    <para>
     Modifiers keywords (public, protected, private) are mandatory in class members and methods definitions. It is recommended to use <parameter>private</parameter> for most members and properties. Use <parameter>public</parameter> only for methods that needs to be accessible from outside the class.
    </para>
    <para>
     In coreplugins or plugins classes, it is generally better to use <parameter>protected</parameter> instead of <parameter>private</parameter> since most methods may have to be redeclared in extended classes (projects plugins). Then only use <parameter>private</parameter> for members/properties you do not want to be redeclared.
    </para>
   </sect3>
   <sect3 id="dev.code_convention.php.style.nesting">
    <title>Nesting</title>
    <para>
     Avoid deep blocks nesting:
    </para>
    <para>This is correct:</para>
     <programlisting><![CDATA[for ($i = 0; $i < 10; i++) {
  if (! something ($i))
    continue;
  doMore();
}]]></programlisting>
   </sect3>
   <sect3 id="dev.code_convention.php.style.tags">
    <title>PHP Code Tags</title>
    <para>
     Always use <programlisting><![CDATA[<?php ?>]]></programlisting> to delimit PHP code, not the <programlisting><![CDATA[<? ?>]]></programlisting> shorthand.
    </para>
   </sect3>
   <sect3 id="dev.code.convention.php.style.naming">
    <title>Naming Conventions</title>
    <sect4 id="dev.code.convention.php.style.naming.classes">
     <title>Classes</title>
     <para>Classes should be given descriptive names that should
     always begin with an uppercase letter. Avoid using abbreviations.</para>
    </sect4>
    <sect4 id="dev.code.convention.php.style.naming.functions">
     <title>Functions and Methods</title>
     <para>
      Functions and methods should be named using the "studly caps"
      style (also referred to as "bumpy case" or "camel caps").</para>
      <programlisting><![CDATA[function handleKeymapTool()]]></programlisting>
     <para>
      Functions and methods names should always describe actions.
     </para>
     <para>
      Developpers should declare the access modifiers (public, private, protected) for each
      function or method.
     </para>
    </sect4>
    <sect4 id="dev.code.convention.php.style.naming.constants">
     <title>Constants</title>
     <para>
      Constants should always be all-uppercase, with underscores to seperate words.
     </para>
    </sect4>
   </sect3>
  </sect2>
  <sect2 id="dev.code_convention.php.comments">
   <title>Comments</title>
   <sect3 id="dev.code_convention.php.comments.doc">
    <title>Php Doc Comments</title>
    <para>
     To improve php code and object structure readability, automatic code
     documentation is implemented in &cartoweb;. It is based on specific comments
     describing classes, methods, interfaces and objects.
     See <xref linkend="dev.code_documentation" /> for more information.
    </para>
   </sect3>
   <sect3 id="dev.code_convention.php.comments.inline">
    <title>Inline Comments</title>
    <para>
     As often as necessary, the developers should add code comments to explain verbosly the
     purposes of commands.
    </para>
   </sect3>
  </sect2>
 </sect1>

 <sect1 id="dev.code_convention.xhtml">
  <title>HTML Coding Standards</title>
  <para>
   In &cartoweb;, mainly for the templates, HTML coding should respect 
   some rules.
  </para>
  <para>
   To take benefits of recent browsers enhancements and, above all, 
   to make HTML codes easier to read and maintain, some HTML-coding 
   guidelines should be followed.
   <itemizedlist>
    <listitem>
     <para>
      for indentation : preferably use 2 white spaces (such an 
      indentation might be used for javascript coding as well).
     </para>
    </listitem>
    <listitem>
     <para>
      Generated HTML pages should be XHTML 1.0 (say 
      Transitional for now) valid and pass matching W3C 
      validation: <ulink url="http://validator.w3.org/">
      http://validator.w3.org/</ulink>
     </para>
    </listitem>
   </itemizedlist>
  </para>
  <para>
   XHTML (standing for eXtensible Hypertext Markup Language) was chosen vs simple HTML for following reasons:
   <itemizedlist> 
    <listitem>
     <para>
      XHTML is aimed to replace HTML
     </para>
    </listitem>
    <listitem>
     <para>
      XHTML is a stricter and cleaner version of HTML
     </para>
    </listitem>
    <listitem>
     <para>
      XHTML is HTML defined as an XML application
     </para>
    </listitem> 
   </itemizedlist>
  </para>
  <para>
   For more information on XHTML, reference and 
   tutorial are available here : <ulink url="http://www.w3schools.com/xhtml/">http://www.w3schools.com/xhtml/</ulink> 
   Specially useful pages are:
   <itemizedlist>
    <listitem>
     <para>
      Differences between HTML and XHTML:
      <ulink url="http://www.w3schools.com/xhtml/xhtml_html.asp">http://www.w3schools.com/xhtml/xhtml_html.asp</ulink>
     </para>
    </listitem>
    <listitem>
     <para>
      XHTML syntax: <ulink url="http://www.w3schools.com/xhtml/xhtml_syntax.asp">http://www.w3schools.com/xhtml/xhtml_syntax.asp</ulink>
     </para>
    </listitem>
   </itemizedlist>
  </para>
  <para>
   But, here are some things people must know to get XHTML valid 
   generated pages.
  </para>
  <sect2 id="dev.code_convention.xhtml.nesting">
   <title>Nesting</title>
   <subtitle>Elements Must Be Properly Nested</subtitle>
   <para>
    In HTML some elements can be improperly nested within each other like this:
    <programlisting><![CDATA[<b><i>This text is bold and italic</b></i>]]></programlisting>
    In XHTML all elements must be properly nested within each other like this:
    <programlisting><![CDATA[<b><i>This text is bold and italic</i></b>]]></programlisting>
    All XHTML elements must be nested within the <![CDATA[<html>]]> root element. All
    other elements can have sub (children) elements. Sub elements must be
    in pairs and correctly nested within their parent element. The basic
    document structure is:
    <programlisting><![CDATA[<html>
  <head> ... </head>
  <body> ... </body>
</html>]]></programlisting>
   </para>
  </sect2>
  <sect2 id="dev.code_convention.xhtml.lower">
   <title>Lower Case</title>
   <subtitle>Tag Names and Attribute Names Must Be in Lower Case</subtitle>
   <para>
    This is because XHTML documents are XML applications.
    XML is case-sensitive. Tags like <![CDATA[<br>]]> and <![CDATA[<BR>]]>
    are interpreted as different tags.
   </para>
   <para>
    This is wrong:
    <programlisting><![CDATA[<BODY>
<P>This is a paragraph</P>
</BODY>]]></programlisting>    
   </para>
   <para>
    This is correct:
    <programlisting><![CDATA[<body>
<p>This is a paragraph</p>
</body>]]></programlisting>    
   </para>
   <para></para>
   <para>
    This is wrong:
    <programlisting><![CDATA[<table WIDTH="100%">]]></programlisting>    
   </para>
   <para>
    This is correct:
    <programlisting><![CDATA[<table width="100%">]]></programlisting>    
   </para>
  </sect2>
  <sect2 id="dev.code_convention.xhtml.closing">
   <title>Closing</title>
   <sect3 id="dev.code_convention.xhtml.element">
    <title>All Elements</title>
    <subtitle>All XHTML Elements Must Be Closed</subtitle>
    <para>
     Non-empty elements must have an end tag.
    </para>
    <para>
     This is wrong:
     <programlisting><![CDATA[<p>This is a paragraph
<p>This is another paragraph]]></programlisting>    
    </para>
    <para>
     This is correct:
     <programlisting><![CDATA[<p>This is a paragraph</p>
<p>This is another paragraph</p>]]></programlisting>    
    </para>
   </sect3>
   <sect3 id="dev.code_convention.xhtml.closing.empty">
    <title>Empty Elements</title>
    <subtitle>Empty Elements Must Also Be Closed</subtitle>
    <para>
     Empty elements must either have an end tag or the start
     tag must end with <![CDATA[/>]]>
    </para>
    <para>
     This is wrong:
     <programlisting><![CDATA[This is a break<br>
Here comes a horizontal rule:<hr>
Here's an image <img src="happy.gif" alt="Happy face">]]></programlisting>    
    </para>
    <para>
     This is correct:
     <programlisting><![CDATA[This is a break<br />
Here comes a horizontal rule:<hr />
Here's an image <img src="happy.gif" alt="Happy face" />
]]></programlisting>
    </para>
    <para>
     IMPORTANT Compatibility Note:
    </para>
    <para>
     To make your XHTML compatible with older browsers,
     you should add an extra space before the "/" symbol like this:
     <![CDATA[<br />]]>, and this: <![CDATA[<hr />]]>. 
    </para>
   </sect3>
  </sect2>
  <sect2 id="dev.code_convention.xhtml.minimization">
   <title>Minimization</title>
   <subtitle>Attribute Minimization Is Forbidden</subtitle>
   <para>
    This is wrong:
    <programlisting><![CDATA[<dl compact>
<input checked>
<input readonly>
<input disabled>
<option selected>
<frame noresize>]]></programlisting>    
   </para>
   <para>
    This is correct:
    <programlisting><![CDATA[<dl compact="compact">
<input checked="checked" />
<input readonly="readonly" />
<input disabled="disabled" />
<option selected="selected" />
<frame noresize="noresize" />
]]></programlisting>
   </para>
   <para>
    Here is a list of the minimized attributes in HTML and how
    they should be written in XHTML:
   </para>
    <programlisting><![CDATA[<dl compact="compact">
<input checked="checked" />
<input readonly="readonly" />
<input disabled="disabled" />
<option selected="selected" />
<frame noresize="noresize" />
]]></programlisting>
  </sect2>
  <sect2 id="dev.code_convention.xhtml.id">
   <title>Id vs Name</title>
   <subtitle>The id Attribute Replaces The name Attribute</subtitle>
   <para>
    HTML 4.01 defines a name attribute for the elements a,
    applet, frame, iframe, img, and map. In XHTML the name
    attribute is deprecated. Use id instead.
   </para>
   <para>
    This is wrong:
   </para>
   <programlisting><![CDATA[<img src="picture.gif" name="picture1" />]]></programlisting>    
   <para>
    This is correct:
   </para>
   <programlisting><![CDATA[<img src="picture.gif" id="picture1" />]]></programlisting>
   <para>
    Note: To interoperate with older browsers for a while,
    you should use both name and id, with identical attribute values,
    like this:
   </para>
   <programlisting><![CDATA[<img src="picture.gif" id="picture1" name="picture1" />]]></programlisting>
   <para>
    IMPORTANT Compatibility Note:
   </para>
   <para>
    To make your XHTML compatible with today's browsers,
    you should add an extra space before the "/" symbol. 
   </para>
  </sect2>
  <sect2 id="dev.code_convention.xhtml.alt">
   <title>Image "alt"</title>
   <subtitle>Tip: Image "alt" Attribute</subtitle>
   <para>
    "alt" attribute is mandatory for <![CDATA[<img />]]> tag in XHTML. But it can -
    and sometimes should - have a void value. "alt" is used to specify
    a replacement text when image is not loaded (image unavailable, not
    yet loaded or user deactivated images...). For "data" images, a convenient
    alternative text should be specified but for layout-only pictos it is
    no use to display a replacement message.
   </para>
   <para>
    For instance:
   </para>
   <programlisting><![CDATA[<img src="mainmap.gif" width="400" height="200"
   alt="Main map" />
<img src="pixel.gif" width="50px" height="1px" alt="" />]]></programlisting>
  </sect2>
 </sect1>
</chapter>
