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). 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 white spaces 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).

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).

Indention

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.

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.

Comments

The classes on-line documentation will follow the PHPDoc convention, that it is alike 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 (//). 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.

Head file comments

All PHP source files will 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

They 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;
}e
lseif ((condition3) && (condition4))
{
action2;
}e
lse
{
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;
break;
}

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

Functions Callings

Functions callings 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

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

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.