OpenClinic Coding Guidelines
- 1. Code Files Format
- 2. Indentation
- 3. Control Structures
- 4. Functions Callings
- 5. Functions Definition
- 6. Comments
-
- 6.1. Head File Comments
- 6.2. Head Module Comments
- 6.3. Head Function Comments
- 6.4. Line Comments
- 7. Including Code
- 8. PHP Code Marks
- 9. Example URLs
- 10. Names Convention
-
- 10.1. Classes
- 10.2. Functions and Methods
- 10.3. Constants
- 10.4. Variables
- 10.5. Global Variables
- 10.6. Predefined Values
- 10.7. Database Fields and Tables Naming
- 10.8. HTML Forms Tag Names
- 10.9. Identifiers Names and HTML Tags Classes
- 11. Code Internationalization
1. Code Files Format
Even it seems that is beside the point this section in this document, it is important know what is the norm we are going to use to write the project source code. It has been adopted the use of 8 bits ASCII code for the code files. The format of the end-of-line character will be UNIX (/10). The reasons for this elections are related to the main idea of promoting the working plataform independence. This format is native for Linux/UNIX users and you can work with this format in Windows too.
Another important thing is knowing which name criteria are going to be followed for file naming.
- It is going to be used lower-case letters in english language and numbers.
- It is not going to be used whitespaces as word separator. Instead it is going to be used hyphens (-), lower-hyphens (_) or dots (we recommend use dots only for distinguish between the name and the extension).
- It is not going to be used accent vowels.
- Remember that a file name can not have this set of characters: \ / : * ? " < > |
- About the name length, it should not be more longer than 128 characters (it is more than needed).
All these guidelines are being done for making possible cross-plataform files without loosing names for a different code page or language.
2. Indentation
It is going to be used 2 spaces (not tabs) for every indentation level. This is to avoid different code display in different tabs configuration. The number 2 is used because it is usually needed a big amount of levels in the source files.
3. Control Structures
Set of control structures: if, for, while, switch, etc. Right down there is an if structure code example:
if ((condition1) || (condition2))
{
action1;
}
elseif ((condition3) && (condition4))
{
action2;
}
else
{
defaultaction;
}
The control structures will have a white-space beteewn the reserved word and the opening parenthesis in order to distinguish from a function calling.
Always are going to be used opening and closing keys in the code. Even if their were optional. This rises the clearness of the code and reduces logical errors that are used when there are added new code-lines. An example of a switch structure:
switch (condition1)
{
case 1:
action1;
break;
case 2:
action2;
break;
default:
defaultaction;
break;
}
The opening and close keys will be always alone in their own line. This is so for code clearness.
4. Functions Callings
Functions callings will be coded with no spaces between name function and the opening parenthesis for paremeters list, neither between the parenthesis named and the first parameter. There will be a white-space between the commas and the the other parameters. There are not going to be spaces between the last parameter and the last parenthesis, neither between this closing parenthesis and the semicolon at the end of the instruction. Here it is an example:
$var = foo($bar, $other, $last);
As it appears in the last example there is a space at the both sides of the equal symbol. In case of there will be more than one assigment it will be right including more spaces (never tabs) for increasing the clearness:
$short = foo($bar);
$longVariable = foo($other, $last);
5. Functions Definition
The functions statements follow the same convention than the control structures: The open and close keys goes in separate lines, as you can see in the following example:
function fooFunction($arg1, $arg2 = '')
{
$var = false;
if (condition)
{
statement;
}
return $val;
}
The arguments with default values will go at the end of the argumets list, before the one's they have not. If the function gives any response at the end of the code, it will go separately from the rest of the code for, al least one blank line. Therefore, if the function declares any variable, this declaration will be done at the begining of the function code and separately from the rest of the code for at least one blank line.
6. Comments
The classes on-line documentation will follow the PHPDoc convention, that it is alike the Javadoc convention. More information about this convention see: PHPDoc web site
The rest of te comments (there are never enought) will use the C style (/* */) and the C++ standard (//). It is not recommended the Perl style (#).
There will co-exist two kind of comments: the head comments (such as comments in the head of a file, a module or a function) and the line comments. The head comments should be used as an introduction, informing the reader about file general things or about the next piece of code. The line comments should be used inside the functions, right between the code, explaining what is really does this line or part of the source code.
6.1. Head File Comments
All PHP source files will include the next head block comment:
/**
* This file is part of Project Name
*
* Copyright (c) Year Author
*
* This program 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.
*
* This program 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 this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
Or instead of this, a smaller version. But this reduced version should always include a file with the kind of license used in the distribution of the program. It would be a good idea to have a head comment like this next one (it could be include PHPDoc directives). Just like the next example (inspired in Zend Framework project):
/**
* file_name.php
*
* Description
*
* Licensed under the GNU GPL. For full terms see the file LICENSE.
*
* @package Project name
* @copyright year author
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL
* @version CVS: $Id: coding_guidelines.html,v 1.17 2013/01/20 12:18:27 jact Exp $
* @author Name <e-mail address> (e-mail optional)
*/
The last example could be followed word for word, but you are free to change the style (between the said ones) and to add more information. Next list shows information suggested by and the order it should be follow (not all the fields are appropiate in all circumstances, of course):
- File name.
- Short description of the archive contents (one line).
- Long description (more detailed) of the file.
- Notes about how to use, requirements, adverts, etc.
- Author name and contact information.
- Creation and last modification date of the file.
- Copyright review.
- License review.
6.2. Head Module Comments
They sould be an informative head right before the first function.
/**
* Module name
*
* Long description (more detailed)
*
* Functions:
* int fileOpen(string $fileName)
* bool fileClose(int $fileHandle)
* int fileRead(int $fileHandle, int $bytes)
*
* Remarks:
* - remark1
* - remark2
*/
Again, there is no matter about the style. Equally there can be included the next elements, in the order they are shown:
- Short description of the module.
- Module detailed description.
- List of function prototypes.
- Notes, remarks and adverts.
6.3. Head Function Comments
The head of a function should describe the sintax, the object and the client information so enough detailed for every function. These comments have to give a quick information to the programmer about needings and specializations of every function during the module developing and extension. They are specially needed for "foreign" developers that do not create the functions originally. Not writting head function comments produces the needing for the new programmer to read all the code looking for information required. This normally produces mistakes because usually you can see all special tricks hide into the code.
/**
* Function prototype
*
* Long description
*
* Parameters:
* $name - description
*
* Return:
* description
*
* Global references:
* $name
*/
Note
It would be a good idea follow the PHPDoc guidelines. Look this example of these guidelines.
/**
* string strText(string $name, int $size, string $value = "", array $addendum = null)
*
* Returns input html tag of type text or password.
*
* @param string $name name of input field
* @param int $size size of text box
* @param string $value (optional) input value
* @param array $addendum (optional) JavaScript event handlers, class attribute, etc
* example:
* $addendum = array(
* 'id' => 'address', // id = name by default
* 'maxlength' => 20,
* 'readonly' => true,
* 'type' => 'password', // text by default
* 'error' => 'The field is required',
* 'class' => 'required',
* 'onclick' => '...'
* );
* @return string input html tag
* @access public
* @since 0.7
*/
A head function comment should have a set of elements like:
- Function prototype.
- Detailed function description.
- Notes, remarks and adverts.
- Parameters description.
- Returned value description.
- Global references.
- Author and last change date.
6.4. Line Comments
The line comments are located right inside the code and they should explain the facts right there where they were.
When you should comment a code, the comment should answer the next list of questions:
- What is it doing so?
- Why is it doing so?
- Why does it do this in that way?
- Why does it right in this moment?
- How does it affect to other part of the program?
- What are the needings of this code?
- Does the method have any inconvenience?
7. Including Code
Wherever a class file is included, it will be used the sentence require_once(). Wherever a class file is included conditionally, it will be used; include_once(). In both cases, the class file will be included only once. Therefore an included file with require_once(), will not be included again wiht include_once().
8. PHP Code Marks
There will be used always the marks <?php ?> as delimiters the PHP code. This makes the code more portable between different operating systems and configurations.
9. Example URLs
It will be used the URL example.com for every example direction, such us it is said in RFC 2606.
10. Names Convention
The class, function and variable names would be as much descriptives as possible ever in order to make easiest the reading and the comprehension of the code.
10.1. Classes
It would be right the use of abbreviations in the name if they do not missunderstood the code. Classes names will always begin with a capital letter. If the are a class hierarchy, every hierarchy level will be separated with a low hyphen (_). Let see some examples:
Log, Net_Finger, HTML_Upload_Error
10.2. Functions and Methods
Functions and methods will be named using the "studly caps" style (also called "bumpy case" or "camel caps"). The methods will include as a prefix their name, the package name they owns to in order to avoid name collisions between different packages. The name first character (after the prefix) will be a capital letter, the rest will go in lower case. Some examples:
connect(), getData(), buildSomeWidget(), XML_RPC_serializeData()
Private class methods and attributes will be preceded in their name by a lower hyphen (_). This is for clearness reasons because PHP does not support private name-spacing yet. Some examples:
_sort(), _initTree(), $this->_status
10.3. Constants
Constans will go always in capital letters, with low hyphens separateing words. The package prefixes will be writeing in capitals too. For example, the constants used in the package DB:: will began "DB_".
10.4. Variables
The right election of a function or variable name is an esencial question at programming time. Generally, when a name is sellected for a variable, it is significant determinate if the variable is global or local. If it is local to a function, the name will be short and precise to express the content or the meaning of this variable. It should have two words maximum, splited by a capital letter. For a looping variable it could be used tipical names, such as ($i, $j, $k, etc.) meanwhile they do not hide information from the code.
$counter, $nextIndex, $nrOptions, $cookieName
10.5. Global Variables
If any package needs to define global variables, their name will begin with a low hyphen, followed by the package name, another low hyphen and at last the assigned name. For example, $_PEAR_destructorObjectList.
10.6. Predefined Values
Predefined PHP values true, false and null will go written always in small letters.
10.7. Database Fields and Tables Naming
Database fields and tables names will go written always in small letters and it will use the symbol _ to separate words. Therefore, table names will have the _tbl subfix. So it will be easy view them between the text.
theme_tbl, session_timeout, items_per_page, id_user
10.8. HTML Forms Tag Names
They will go always in small letters and it will use the _ sign as a separator character. This style has been chosen to make more distinguisable the database fields from the class method names whom manages them.
collegiate_number, first_name, phone_contact, login
10.9. Identifiers Names and HTML Tags Classes
Are going to be used the same rules than in variable naming to name identifiers. As class attributes values, it is valid the use of blank space but only as separator. In this way it is possible to add more than one class at the same time at the same element.
One advice: not mix styles. Or you use the symbol - to separate words (symbol _ is forbidden to name identifiers ans class names) or you follow the rules for variable naming (except the symbol $).
This is extensible to the files which have HTML styles (.css files) or incrusted stylesheets in the code.
11. Code Internacionalization
One of the most normal critics to the source codes are about the "localization". The mix between the programming language (that normally has an english background) with another language. As this project will be GPL licensed and english is the in fact an international standard and more or less understanded by most of the community, we should try to use the english language as naming standard for variables, functions, classes, methods, constants and comments. We hope with this make the code more understable for people from other languages.
