|
|
| (15 intermediate revisions by 7 users not shown) |
| Line 1: |
Line 1: |
| = Code Files Format=
| | This page contains guidelines that are not covered by the Zend Framework standard, or where ATK uses a different convention for historical/backwards compatible reasons. |
| 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 =
| | We are aware that many files in our products do not yet adhere to the above guidelines, since they've had many years of coding to different standards. We will gradually adjust those files. |
| 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 = | | = Naming conventions = |
| 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 =
| | We follow the Zend Framework naming conventions for classes, with the following exceptions: |
| 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 ==
| | * Until ATK's directory structure has been converted to match a Zend Framework directory layout (see [[ATK/Zend Framework integration]]), ATK classes use its historical 'atkClassName' convention. |
| All PHP source files will include the next head block comment:
| | * Nodes are considered business entities and are named in common english in all-lowercase, for example: |
| <syntaxhighlight lang="php"> | | <syntaxhighlight lang="php">class employee extends atkMetaNode</syntaxhighlight> |
| /**
| |
| * 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 $
| |
| */
| |
| </syntaxhighlight> | |
|
| |
|
| == Class comments == | | = Comments = |
| They should be an informative head right before the first function.
| |
| <syntaxhighlight lang="php">
| |
| /**
| |
| * Class description
| |
| *
| |
| * @author Name <email address >
| |
| * @package atk
| |
| */
| |
| </syntaxhighlight>
| |
|
| |
|
| == Function comments == | | == Header for ATK == |
| The head of a function should describe the syntax, the object and the client information
| | For ATK scripts, the file header is: |
| 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.
| |
| <syntaxhighlight lang="php">
| |
| /**
| |
| * Function description
| |
| * @param type name description
| |
| * @return type description
| |
| */
| |
| </syntaxhighlight>
| |
|
| |
|
| == Variable comments ==
| |
| <syntaxhighlight lang="php"> | | <syntaxhighlight lang="php"> |
| /** | | /** |
| * Variable description | | * This file is part of the ATK Framework distribution. |
| * @access | | * Detailed copyright and licensing information can be found |
| * @var
| | * in the doc/COPYRIGHT and doc/LICENSE files which should be |
| */ | | * included in the distribution. |
| </syntaxhighlight>
| | * |
| | | * @package atk |
| == Line comments ==
| | * @subpackage ... |
| The line comments are located right inside the code and they should explain the facts
| | * |
| right there where they were.
| | * @copyright (c)2000-2010 Ivo Jansch |
| When you should comment a code, the comment should answer the next list of questions:
| | * @copyright (c)2000-2010 Ibuildings.nl BV |
| * What is it doing so? | | * @license LGPL - http://www.atk-framework.com/licensing |
| * Why is it doing so?
| | * |
| * Why does it do this in that way?
| | * @version $Revision$ |
| * Why does it right in this moment? | | * $Id$ |
| * 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:
| |
| <syntaxhighlight lang="php">
| |
| if ((condition1) || (condition2))
| |
| {
| |
| action1;
| |
| }e
| |
| lseif ((condition3) && (condition4))
| |
| {
| |
| action2;
| |
| }e
| |
| lse
| |
| {
| |
| defaultaction;
| |
| }
| |
| </syntaxhighlight>
| |
| | |
| 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:
| |
| <syntaxhighlight lang="php">
| |
| switch (condition1)
| |
| {
| |
| case 1:
| |
| action1;
| |
| break;
| |
| case 2:
| |
| action2;
| |
| break;
| |
| default:
| |
| defaultaction;
| |
| break;
| |
| }
| |
| </syntaxhighlight>
| |
| 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:
| |
| | |
| <syntaxhighlight lang="php">
| |
| $var = foo($bar, $other, $last); | |
| </syntaxhighlight>
| |
| | |
| 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:
| |
| <syntaxhighlight lang="php">
| |
| $short = foo($bar);
| |
| $longVariable = foo($other, $last);
| |
| </syntaxhighlight> | | </syntaxhighlight> |
| = 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:
| |
| <syntaxhighlight lang="php">
| |
| function fooFunction($arg1, $arg2 = '')
| |
| {
| |
| $var = false;
| |
| if (condition)
| |
| {
| |
| statement;
| |
| }
| |
| return $val;
| |
| }
| |
| </syntaxhighlight>
| |
| 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.
| |
