[Koha-devel] Draft of coding guidelines
Stephen Hedges
shedges at athenscounty.lib.oh.us
Tue Jun 14 18:44:33 CEST 2005
Attached to this message is a draft of a document called "Koha Coding
Standards and Guidelines for Contributors." The release managers (past
and present) and the Kaitiaki have had a chance to look this over and
make comments -- now it's your turn!
The xml source of this document is on Sourceforge under the koha-doc
directory (http://cvs.sourceforge.net/viewcvs.py/koha/koha-doc/), so
you can make minor changes there, if you want. Major changes should be
discussed on the mailing list, however.
Once we agree on the content of the document, we should get it
translated into French, Spanish, and German. I think the final
version(s) should be posted in CVS, on kohadocs.org, and in the
Sourceforge Koha Document Manager
(http://cvs.sourceforge.net/viewcvs.py/koha/koha-doc/) -- anywhere
else?
Stephen Hedges
Koha Coding Standards and Guidelines for Contributors
1. Introduction
2. Code style
2.1. HTML
2.1.1. Templates location
2.1.2. Online help
2.1.3. Template content
2.2. DB access
2.3. Perl scripts
2.4. Naming conventions
2.4.1. Script names
2.4.2. Variable names
3. Commenting style
4. POD style (in modules)
1. Introduction
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.
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.
2. Code style
Koha code should conform to the guidelines defined in the perlstyle 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:
•
the Perl code;
•
the database (DB) access code; and
•
the HTML code.
These three code types, as well as the Koha naming conventions, are
explained in the following sections.
2.1. HTML
All code controlling the "appearance layer" is contained in
HTML::Template files. These files are located in the koha-tmpl
directory in CVS (currently
http://sourceforge.net/cvs/?group_id=16466). They must contain all the
code controlling the presentation layer. There are at least two good
reasons for this:
•
the look of Koha can be changed by rewriting only the templates,
changing nothing in the Perl code itself; and
•
there is a tool to translate templates, so it's the only way to
localise our preferred ILS.
Almost all the actual Koha presentation pages use templates. Only a few
exceptions (that can be considered bugs) remain at the time of writing.
2.1.1. Templates location
The koha-tmpl directory contains two different sub-directories:
opac-tmpl and intranet-tmpl. Under those two are the themes
directories, and one directory for each language -- for example,
intranet-tmpl/default/en 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
$KOHA/acqui.simple directory should use templates located in
$KOHA/koha-tmpl/intranet-tmpl/<theme>/<language>/acqui.simple.
Exceptions:
•
Scripts located in $KOHA/admin/ use templates located in
$KOHA/intranet-tmpl/<theme>/<language>/parameters/
•
Some scripts in $KOHA/members/ use templates located in
$KOHA/intranet-tmpl/<theme>/<language>/
•
Simple HTML "includes" files for placing standard headers and footers
on Koha pages are located in
$KOHA/intranet-tmpl/<theme>/<language>/includes/
When modifying templates, you should only modify the English one
manually. All other languages are automatically generated from the
English templates through a .po file and the script located in
misc/translator/tmpl_process3.pl.
2.1.2. Online help
The $KOHA/koha-tmpl/<theme>/<language>/help directory contains online
help. Under the help 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 $KOHA/help.pl script is
called when the user clicks on "Help," which opens/shows the templates
in this directory.
PLEASE write online help when you add features.
2.1.3. Template content
There is usually only one template for a given .pl file. For example,
the template related to circulation/returns.pl should be
circulation/returns.tmpl.
If there are different possible behaviours, they should be separated by
a TMPL_IF. For example,
$KOHA/koha-tmpl/intranet-tmpl/<theme>/<language>/parameters contains:
<!-- TMPL_IF name="add_form" -->
that controls what is shown when the user wants to add something (as
determined by the Perl script):
if ($op) {
$template->param(script_name => $script_name,
$op => 1); # We show only the TMPL_VAR names $op.
} else {
$template->param(script_name => $script_name,
else => 1); # We show only the TMPL_VAR names $op.
}
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 $KOHA/opac/opac-search.pl, we can use
the opac-search or opac-searchresults 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.
2.2. DB access
No database (DB) access routines should ever be included in .pl files.
All DB access routines should be in the C4 directory, in .pm modules.
There is one .pm module for each logical "librarian activity." For
example, everything related to circulation must be in
C4/Circulation/Circ2.pm.
All inclusion of Perl variables in SQL commands should be done through
prepare() statements with ? placeholders, and then using bind() and/or
execute() calls. This helps with security and other testing.
The C4/Context.pm module contains everything related to technical
variables (creating a DB handler, getting a systempreference, etc.).
The C4/Koha.pm 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.)
Exception: parameters management scripts. For historic reasons, and
because they don't do anything complex in the database, all scripts in
$KOHA/admin/ 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.")
2.3. Perl scripts
Perl scripts are the scripts that are run from cgi-bin (or mod_perl).
They all have (almost) the same behaviour:
•
read parameters;
•
open an HTML::Template 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);
•
depending on the parameters (often, in a $op variable, but not always),
run subroutines from a C4/*.pm package to do something in the database;
•
using the parameters and the results of the previous operations, fill
the template; and
•
send the template to the user.
Some scripts are run on the command line. They all are located in the
misc directory. The misc directory does not contain any scripts that
can be run as cgi-bin.
Command line scripts executed without any parameters should return a
"help" listing of possible parameters and exit without doing anything.
2.4. Naming conventions
2.4.1. Script names
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
$KOHA/circ/.
Exceptions:
•
The acqui.simple directory contains all the code for MARC cataloguing.
The directory name obviously is not related to the "librarian
activity," but it's historic.
•
The bull 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.
•
Some scripts related to borrowers are still in the $KOHA/ directory
(pay.pl for example).
2.4.2. Variable names
Variables can be of three types:
•
Perl variables;
•
template variables; or
•
hash entries from a SQL request.
All three variables should have the same name. For example, if you get
the field issuelength from the issuingrules table, then you should have
a <!-- TMPL_VAR name="issuelength" --> in the template, and either a
$issuelength or $issuingrules->{'issuelength'} variable in the Perl
code.
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 borrowers.surname, use
librariansurname and borrowersurname.
3. Commenting style
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:
1
Please write your comments in English or request translation.
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).
Comments should start with a # and a single space.
2
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.
3
Each Koha file should begin with a block comment containing:
a
basic information about the file, such as file name, version, date,
author:
# addbiblio.pl, v 1.52.2.6, 2005/05/19, tipaul
b
the standard Koha copyright message:
# Copyright 2000-2005 Katipo Communications
# Copyright 2005 <author or employer>
#
# 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
4
All block comments should consist of one or more paragraphs built out
of complete sentences, and each sentence should end in a period.
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.
5
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.
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.
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.
6
Use comments on code that consists of loops and logic branches. These
are key areas that will assist the reader when reading source code.
7
Try to avoid adding comments at the end of a line of code; end-line
comments make code more difficult to read.
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.)
8
When modifying code, always keep the commenting around it up to date.
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.
9
Avoid using clutter comments, such as an entire line of asterisks.
Instead, use white space to separate comments from code.
Avoid the use of superfluous or inappropriate comments, such as
humorous sidebar remarks.
10
To prevent recurring problems, always use comments on bug fixes and
work-around code, especially in this team environment.
When you want to leave notes about functionalities to be added, put
TODO: in front of the actual comments so developers can easily search
for them.
When you want to leave notes about bugs to be fixed, put FIXME: in
front of the actual comments so developers can easily search for them.
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.
4. POD style (in modules)
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 perlpod man page.
POD comments should include as least the following headings:
NAME
The name of the module and a very brief description of the type of
functions contained in the module.
SYNOPSIS
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.
DESCRIPTION
If not included in the SYNOPSIS, a general description of the module's
purpose should appear here.
FUNCTIONS
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.
AUTHOR
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.
For two examples, see the POD comments in the Search.pm module (perldoc
Search.pm) and the Biblio.pm module.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: text/enriched
Size: 18168 bytes
Desc: not available
URL: </pipermail/koha-devel/attachments/20050614/6b25fefc/attachment-0002.bin>
More information about the Koha-devel
mailing list