Revision as of 13:48, 9 January 2008

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 using to write the project source code. It has been adopted to use 8 bits ASCII code for the code files. The format of the end-of-line character is UNIX (/10). 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 must be met for file naming.

Use lower-case letters in English language and numbers.
Do NOT use white spaces as word separator. Instead use hyphens (-), lower-hyphens (_) or dots (we recommend to use dots only to

distinguish the file name and the file extension).

Remember that a file name can not have any of these characters: \ / : * ? " < > |
The file name length should not exceed 128 characters (should be more than enough).

Indentation

Use 2 spaces (not tabs) for every indentation level. This is to avoid different code views in different tab configurations. The number of spaces is 2 because often a lot of levels are used in source code and this will keep the code a bit more readable.

PHP Code Marks

Always use the marks <?php ?> as delimiters the PHP code. This makes the code more portable between different operating systems and configurations.

Comments

The on-line class documentation will follow the PHPDoc convention, much like the Javadoc convention. More information about this convention see: http://www.phpdoc.de The rest of the comments (there are never enough) will use the C style (/* */) and the C++ standard (//). The Perl style is not recommended (#). Two kind of comments co-exist: 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 actions are performed in the following line(s) of code.

Head file comments

All PHP source files must include the next head block comment:

/**
* This file is part of the Achievo ATK distribution.
* Detailed copyright and licensing information can be found
* in the doc/COPYRIGHT and doc/LICENSE files which should be
* included in the distribution.
*
* @package atk
*
* @copyright (c)2000-2004 Ivo Jansch
* @copyright (c)2000-2004 Ibuildings.nl BV
* @license http://www.achievo.org/atk/licensing ATK Open Source License
*
* @version $Revision$
* $Id $
*/

Class comments

There should be an informative head right before the first function.

/**
* Class description
*
* @author Name <email address >
* @package atk
*/

Function comments

The head of a function should describe the syntax, 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 writing 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 description
* @param type name description
* @return type description
*/

Variable comments

/**
* Variable description
* @access
* @var
*/

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?

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 with include_once().

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 between 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;
}

The opening and close keys will be always alone in their own line. This is so for code clearness.

Function Calls

Function calls will be coded with no spaces between name function and the opening parenthesis for parameters list, neither between the parenthesis named and the first parameter. There will be a white-space between the commas and 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 assignment it will be right including more spaces (never tabs) for increasing the clearness:

$short = foo($bar);
$longVariable = foo($other, $last);

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 arguments 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 beginning of the function code and separately from the rest of the code for at least one blank line.

Names Convention

The class, function and variable names would be as much descriptive as possible ever in order to make easiest the reading and the comprehension of the code.

Classes

Classnames should have a prefix, which is lowercased. All words in a classname start with a capital. Example: atkClassName.

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

Constants

Constants will go always in capital letters, with low hyphens separating words.

Variables

The right election of a function or variable name is an essential question at programming time. Generally, when a name is selected 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 typical names, such as ($i, $j, $k, etc.) meanwhile they do not hide information from the code. $counter, $nextIndex, $nrOptions, $cookieName

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.

Predefined Values

Predefined PHP values true, false and null will go written always in small letters.

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

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

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 as 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 style sheets in the code.

SQL code

When writing SQL queries, capitalize all SQL keywords (SELECT, FROM, VALUES, AS etc.) and leave everything else in the relevant case. If you are using WHERE clauses to return data corresponding to a set of conditions, enclose those conditions in brackets in the same way you would for PHP if blocks, e.g. <sql> SELECT * FROM users WHERE ( (registered = 'y') AND ((user_level = 'administrator') OR (user_level = 'moderator')) ). </sql>

Code Internationalization

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.