[Koha-cvs] CVS: koha-doc codingguidelines.xml,NONE,1.1

[skemotah]

Update of /cvsroot/koha/koha-doc
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv4193

Added Files:
	codingguidelines.xml 
Log Message:
draft of coding standards and guidelines

--- NEW FILE ---
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<article>
  <title>Koha Coding Standards and Guidelines for Contributors</title>

  <section>
    <title>Introduction</title>

    <para>As in other free and open source software projects, Koha contains
    code that has been contributed to the project by many different
    developers. Koha is now a complex piece of software, and we'd like
    continue to improve the overall code standards to make it easier for new
    developers to join the project, and to make existing code easier to
    maintain. These standards and guidelines are intended to give Koha a
    reasonably consistent style throughout the code and to ensure
    maintainability.</para>

    <para>When you commit new code to Koha, please do your best to comply with
    these guidelines -- it will increase the chances of your code become part
    of a stable Koha release. And if you find code in Koha that doesn't comply
    with these guidelines, please feel free to fix it, just as you would
    correct any bug.</para>
  </section>

  <section>
    <title>Code style</title>

    <para>Koha code should conform to the guidelines defined in the <ulink
    url="http://perldoc.perl.org/perlstyle.html">perlstyle</ulink> man page as
    they apply to code details (indenting, etc.). As for the general structure
    of the code, all Koha code must be separated into three types:</para>

    <itemizedlist>
      <listitem>
        <para>the Perl code;</para>
      </listitem>

      <listitem>
        <para>the database (DB) access code; and</para>
      </listitem>

      <listitem>
        <para>the HTML code.</para>
      </listitem>
    </itemizedlist>

    <para>These three code types, as well as the Koha naming conventions, are
    explained in the following sections.</para>

    <section>
      <title>HTML</title>

      <para>All code controlling the "appearance layer" is contained in
      <filename>HTML::Template</filename> files. These files are located in
      the <filename>koha-tmpl</filename> directory in CVS (currently <ulink
      url="http://sourceforge.net/cvs/?group_id=16466">http://sourceforge.net/cvs/?group_id=16466</ulink>).
      They must contain all the code controlling the presentation layer. There
      are at least two good reasons for this:</para>

      <itemizedlist>
        <listitem>
          <para>the look of Koha can be changed by rewriting only the
          templates, changing nothing in the Perl code itself; and</para>
        </listitem>

        <listitem>
          <para>there is a tool to translate templates, so it's the only way
          to localise our preferred ILS.</para>
        </listitem>
      </itemizedlist>

      <para>Almost all the actual Koha presentation pages use templates. Only
      a few exceptions (that can be considered bugs) remain at the time of
      writing.</para>

      <section>
        <title>Templates location</title>

        <para>The <filename>koha-tmpl</filename> directory contains two
        different sub-directories: <filename>opac-tmpl</filename> and
        <filename>intranet-tmpl</filename>. Under those two are the themes
        directories, and one directory for each language -- for example,
        <filename>intranet-tmpl/default/en</filename> for English default
        templates. The templates should be stored in a directory that
        parallels the location of the Perl scripts. For example, the Perl
        scripts located in the <filename>$KOHA/acqui.simple</filename>
        directory should use templates located in
        <filename>$KOHA/koha-tmpl/intranet-tmpl/&lt;theme&gt;/&lt;language&gt;/acqui.simple</filename>.</para>

        <para><emphasis>Exceptions:</emphasis></para>

        <itemizedlist>
          <listitem>
            <para>Scripts located in <filename>$KOHA/admin/</filename> use
            templates located in
            <filename>$KOHA/intranet-tmpl/&lt;theme&gt;/&lt;language&gt;/parameters/</filename></para>
          </listitem>

          <listitem>
            <para>Some scripts in <filename>$KOHA/members/</filename> use
            templates located in
            <filename>$KOHA/intranet-tmpl/&lt;theme&gt;/&lt;language&gt;/</filename></para>
          </listitem>

          <listitem>
            <para>Simple HTML "includes" files for placing standard headers
            and footers on Koha pages are located in
            <filename>$KOHA/intranet-tmpl/&lt;theme&gt;/&lt;language&gt;/includes/</filename></para>
          </listitem>
        </itemizedlist>

        <para>When modifying templates, you should only modify the English one
        manually. All other languages are automatically generated from the
        English templates through a <filename>.po</filename> file and the
        script located in
        <filename>misc/translator/tmpl_process3.pl</filename>.</para>
      </section>

      <section>
        <title>Online help</title>

        <para>The
        <filename>$KOHA/koha-tmpl/&lt;theme&gt;/&lt;language&gt;/help</filename>
        directory contains online help. Under the <filename>help</filename>
        directory is a complete copy of the Koha directory structure, with
        templates using the same name as the "true" templates. These templates
        must contain online help. The <filename>$KOHA/help.pl</filename>
        script is called when the user clicks on "Help," which opens/shows the
        templates in this directory.</para>

        <para>PLEASE write online help when you add features.</para>
      </section>

      <section>
        <title>Template content</title>

        <para>There is usually only one template for a given
        <filename>.pl</filename> file. For example, the template related to
        <filename>circulation/returns.pl</filename> should be
        <filename>circulation/returns.tmpl</filename>.</para>

        <para>If there are different possible behaviours, they should be
        separated by a <varname>TMPL_IF</varname>. For example,
        <filename>$KOHA/koha-tmpl/intranet-tmpl/&lt;theme&gt;/&lt;language&gt;/parameters</filename>
        contains:</para>

        <programlisting>&lt;!-- TMPL_IF name="add_form" --&gt;</programlisting>

        <para>that controls what is shown when the user wants to add something
        (as determined by the Perl script):</para>

        <programlisting>if ($op) {
$template-&gt;param(script_name =&gt; $script_name,
$op              =&gt; 1);  # We show only the TMPL_VAR names $op.
} else {
$template-&gt;param(script_name =&gt; $script_name,
else              =&gt; 1); # We show only the TMPL_VAR names $op.
}</programlisting>

        <para>Note that some scripts use two different templates, depending on
        what the user wants to do. This is sometimes a mistake in Koha design,
        sometimes not. For example, in
        <filename>$KOHA/opac/opac-search.pl</filename>, we can use the
        <filename>opac-search</filename> or
        <filename>opac-searchresults</filename> template, depending on the
        step of the search. Both templates are big, so merging them would not
        be a good idea for maintenance and readability of Koha code.</para>
      </section>
    </section>

    <section>
      <title>DB access</title>

      <para>No database (DB) access routines should ever be included in
      <filename>.pl</filename> files. All DB access routines should be in the
      <filename>C4</filename> directory, in <filename>.pm</filename> modules.
      There is one <filename>.pm</filename> module for each logical "librarian
      activity." For example, everything related to circulation must be in
      <filename>C4/Circulation/Circ2.pm</filename>.</para>

      <para>All inclusion of Perl variables in SQL commands should be done
      through <userinput>prepare()</userinput> statements with
      <userinput>?</userinput> placeholders, and then using
      <userinput>bind()</userinput> and/or <userinput>execute()</userinput>
      calls. This helps with security and other testing.</para>

      <para>The <filename>C4/Context.pm</filename> module contains everything
      related to technical variables (creating a DB handler, getting a
      systempreference, etc.).</para>

      <para>The <filename>C4/Koha.pm</filename> module contains everything
      related to things that are useful everywhere in Koha, such as getting a
      branch list or a branch detail. (At the time of writing, this module
      probably should be improved. Some subroutines, for instance, are located
      in other modules but would be better here.)</para>

      <para><emphasis>Exception:</emphasis> parameters management scripts. For
      historic reasons, and because they don't do anything complex in the
      database, all scripts in <filename>$KOHA/admin/</filename> deal directly
      with the database. This is not really a bug, even if it does seem to
      break the rule. (Think of it as "the exception that proves the
      rule.")</para>
    </section>

    <section>
      <title>Perl scripts</title>

      <para>Perl scripts are the scripts that are run from
      <filename>cgi-bin</filename> (or <filename>mod_perl</filename>). They
      all have (almost) the same behaviour:</para>

      <itemizedlist>
        <listitem>
          <para>read parameters;</para>
        </listitem>

        <listitem>
          <para>open an <filename>HTML::Template</filename> file (that checks
          the user rights to access the page if needed -- if the user doesn't
          have the correct permissions, show a "sorry no access" page and
          end);</para>
        </listitem>

        <listitem>
          <para>depending on the parameters (often, in a
          <varname>$op</varname> variable, but not always), run subroutines
          from a <filename>C4/*.pm</filename> package to do something in the
          database;</para>
        </listitem>

        <listitem>
          <para>using the parameters and the results of the previous
          operations, fill the template; and</para>
        </listitem>

        <listitem>
          <para>send the template to the user.</para>
        </listitem>
      </itemizedlist>

      <para>Some scripts are run on the command line. They all are located in
      the <filename>misc</filename> directory. The <filename>misc</filename>
      directory does not contain any scripts that can be run as
      <filename>cgi-bin</filename>.</para>

      <para>Command line scripts executed without any parameters should return
      a "help" listing of possible parameters and exit without doing
      anything.</para>
    </section>

    <section>
      <title>Naming conventions</title>

      <section>
        <title>Script names</title>

        <para>The script names must be related to what they do, and they must
        be located in a directory that is related to a logical "librarian
        activity". For example, all scripts related to circulation are in
        <filename>$KOHA/circ/</filename>.</para>

        <para><emphasis>Exceptions:</emphasis></para>

        <itemizedlist>
          <listitem>
            <para>The <filename>acqui.simple</filename> directory contains all
            the code for MARC cataloguing. The directory name obviously is not
            related to the "librarian activity," but it's historic.</para>
          </listitem>

          <listitem>
            <para>The <filename>bull</filename> directory is related to
            serials management. Most of the code in this directory was
            developed in France, and "serials management" is "bulletinage" in
            French -- but in general, script and directory names should be in
            English.</para>
          </listitem>

          <listitem>
            <para>Some scripts related to borrowers are still in the
            <filename>$KOHA/</filename> directory (<filename>pay.pl</filename>
            for example).</para>
          </listitem>
        </itemizedlist>
      </section>

      <section>
        <title>Variable names</title>

        <para>Variables can be of three types:</para>

        <itemizedlist>
          <listitem>
            <para>Perl variables;</para>
          </listitem>

          <listitem>
            <para>template variables; or</para>
          </listitem>

          <listitem>
            <para>hash entries from a SQL request.</para>
          </listitem>
        </itemizedlist>

        <para>All three variables should have the same name. For example, if
        you get the field <varname>issuelength</varname> from the
        <filename>issuingrules</filename> table, then you should have a
        <userinput>&lt;!-- TMPL_VAR name="issuelength" --&gt;</userinput> in
        the template, and either a <varname>$issuelength</varname> or
        <varname>$issuingrules-&gt;{'issuelength'}</varname> variable in the
        Perl code.</para>

        <para>Sometimes you must use the same field/variable from two
        different points of view. In this case, use two variable names, with
        something distinctive before the "simple" name. For example if you
        need "librarian name" and "borrower name" from
        <varname>borrowers.surname</varname>, use
        <varname>librariansurname</varname> and
        <varname>borrowersurname</varname>.</para>
      </section>
    </section>
  </section>

  <section>
    <title>Commenting style</title>

    <para>Scripts and modules in Koha are expected to contain clear and
    helpful comments to assist other developers who want to work on the code.
    Despite the availability of external documentation, source code listings
    should be able to stand on their own, because external documentation may
    not adequately describe the details and intent of the developer(s). Please
    make sure you include enough comments to keep your coding intentions
    understandable, and try to follow these guidelines:</para>

    <orderedlist>
      <listitem>
        <para>Please write your comments in English or request
        translation.</para>

        <para>Write in complete sentences, capitalize the first word, and put
        two spaces after the end of each sentence (so that the Emacs sentence
        commands will work).</para>

        <para>Comments should start with a # and a single space.</para>
      </listitem>

      <listitem>
        <para>Comment your code when you do something that someone else may
        not think is "trivial." In other words, comment anything that is not
        readily obvious in the code.</para>
      </listitem>

      <listitem>
        <para>Each Koha file should begin with a block comment
        containing:</para>

        <orderedlist>
          <listitem>
            <para>basic information about the file, such as file name,
            version, date, author:<programlisting># addbiblio.pl, v 1.52.2.6, 2005/05/19, tipaul</programlisting></para>
          </listitem>

          <listitem>
            <para>the standard Koha copyright message:<programlisting># Copyright 2000-2005 Katipo Communications
# Copyright 2005 &lt;author or employer&gt;
#
# This file is part of Koha.
#
# Koha is free software; you can redistribute it and/or modify it under the
# terms of the GNU General Public License as published by the Free Software
# Foundation; either version 2 of the License, or (at your option) any later
# version.
#
# Koha is distributed in the hope that it will be useful, but WITHOUT ANY
# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
# A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License along with
# Koha; if not, write to the Free Software Foundation, Inc., 59 Temple Place,
# Suite 330, Boston, MA  02111-1307 USA</programlisting></para>
          </listitem>
        </orderedlist>
      </listitem>

      <listitem>
        <para>All block comments should consist of one or more paragraphs
        built out of complete sentences, and each sentence should end in a
        period.</para>

        <para>Block comments generally apply to some (or all) code that
        follows them, and are indented to the same level as that code. Each
        line of a block comment starts with a # and a single space (unless it
        is indented text inside the comment). Paragraphs inside a block
        comment are separated by a line containing a single #. Block comments
        are best surrounded by a blank line above and below them.</para>
      </listitem>

      <listitem>
        <para>Provide comments at the beginning of every function (unless the
        function is very short and its purpose is obvious) indicating the
        function's purpose, assumptions, and limitations.</para>

        <para>The comments should be a brief introduction to understand why
        the function exists and what it can do. Document how it does it, too,
        if that is not obvious.</para>

        <para>Place a blank line between a function and its description.
        Include information about the sorts of arguments it gets, and what the
        possible values of arguments mean and are used for. Also explain the
        significance of the return value, if there is one.</para>
      </listitem>

      <listitem>
        <para>Use comments on code that consists of loops and logic branches.
        These are key areas that will assist the reader when reading source
        code.</para>
      </listitem>

      <listitem>
        <para>Try to avoid adding comments at the end of a line of code;
        end-line comments make code more difficult to read.</para>

        <para>End-line comments are appropriate, however, when annotating
        variable declarations. In this case, try to align all end-line
        comments at a common tab stop. (End-line comments should be separated
        by at least two spaces from the statement.)</para>
      </listitem>

      <listitem>
        <para>When modifying code, always keep the commenting around it up to
        date.</para>

        <para>Keeping the comments up-to-date when the code changes is a
        priority -- comments that contradict the code are worse than no
        comments! Identify the change with the date and your user name.</para>
      </listitem>

      <listitem>
        <para>Avoid using clutter comments, such as an entire line of
        asterisks. Instead, use white space to separate comments from
        code.</para>

        <para>Avoid the use of superfluous or inappropriate comments, such as
        humorous sidebar remarks.</para>
      </listitem>

      <listitem>
        <para>To prevent recurring problems, always use comments on bug fixes
        and work-around code, especially in this team environment.</para>

        <para>When you want to leave notes about functionalities to be added,
        put <userinput>TODO:</userinput> in front of the actual comments so
        developers can easily search for them.</para>

        <para>When you want to leave notes about bugs to be fixed, put
        <userinput>FIXME:</userinput> in front of the actual comments so
        developers can easily search for them.</para>
      </listitem>
    </orderedlist>

    <para>One other type of comment that developers may overlook is the cvs
    log message added when committing a file, but these comments are also very
    important. The messages should never be omitted and should give enough
    description to let other developers know what you are doing without having
    to read the code itself. In the case of bug fixes, it is also recommended
    that the messages include the bug number and the bug title, as well as a
    brief description of the fix.</para>
  </section>

  <section>
    <title>POD style (in modules)</title>

    <para>Koha modules should be documented with extensive comments written in
    POD ("Plain Old Documentation") format. Instructions for the POD markup
    language can be found in the <ulink
    url="http://perldoc.perl.org/perlpod.html">perlpod</ulink> man
    page.</para>

    <para>POD comments should include as least the following headings:</para>

    <variablelist>
      <varlistentry>
        <term>NAME</term>

        <listitem>
          <para>The name of the module and a very brief description of the
          type of functions contained in the module.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>SYNOPSIS</term>

        <listitem>
          <para>This may give an example of how to access the module from a
          script, but it may also contain any general discussion of the
          purpose or behavior of the module's functions, and discussion of
          changes made to the module.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>DESCRIPTION</term>

        <listitem>
          <para>If not included in the SYNOPSIS, a general description of the
          module's purpose should appear here.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>FUNCTIONS</term>

        <listitem>
          <para>Descriptions of each function in the module, beginning with an
          example of how the function is called and continuing with a
          description of the behavior of the function.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>AUTHOR</term>

        <listitem>
          <para>This will generally be the "Koha Development Team," but may
          also be an individual developer who has made significant
          contributions to the module. Give a contact e-mail address.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>For two examples, see the POD comments in the
    <filename>Search.pm</filename> module (<userinput>perldoc
    Search.pm</userinput>) and the <filename>Biblio.pm</filename>
    module.</para>
  </section>
</article>