Jump to content

Coding Guidelines: Difference between revisions

From NusaATK
← Older edit
Bahati (talk | contribs)
Administrators
0 edits
Martin (talk | contribs)
0 edits
it was violated the coding guideline rules
No edit summary
 
(5 intermediate revisions by 2 users not shown)
Line 1: Line 1:
= Files =
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.
* Keep filenames short
* Use lowercase characters only
* Extensions:
** Only use .php extension for those files that should be browsable.
** Use .inc for files that are included
** Use .lng for language files
** Use .tpl for template files
* For classes, use the class.classname.inc convention
* For interfaces, use the interface.interfacename.inc convention


= Indentation =
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.
Use 2 spaces (not tabs) for every indentation level. We are aware of the religious wars surrounding 'tabs vs. spaces', but have chosen spaces for various reasons, and more important than choosing either of the two, is sticking to what you've chosen.


= PHP delimiters =
= Naming conventions =
Use the long tags:


  <?php
We follow the Zend Framework naming conventions for classes, with the following exceptions:
  ?>


Do not use short tags as they are not always enabled on all environments, and may conflict with other tags (such as the XML opening tag).
* 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.
 
* Nodes are considered business entities and are named in common english in all-lowercase, for example:
For brackets, we use 'Allman style' (http://en.wikipedia.org/wiki/Indent_style#Allman_style). In short, this means opening brackets are on the next line:
<syntaxhighlight lang="php">class employee extends atkMetaNode</syntaxhighlight>
 
<syntaxhighlight lang="php">
  while ($i<10)
  {
    echo $i;
  }
</syntaxhighlight>


= Comments =
= Comments =
Code documentation should use the phpdoc convention. We use phpDocumentor (http://www.phpdoc.org) to generate online API docs from the source code.
For documentation inside of functions, we use // for single line comments or /* */ for multiline comments.
Every file should have a file header. All Ibuildings products have their own template for this (copy from one of the existing files) and it is recommended that projects derive their own version from one of these headers.


== Header for ATK ==
== Header for ATK ==
For ATK scripts, the file header is:
For ATK scripts, the file header is:
<syntaxhighlight lang="php">
<syntaxhighlight lang="php">
/**
/**
  * This file is part of the Achievo ATK distribution.
  * This file is part of the ATK Framework distribution.
  * Detailed copyright and licensing information can be found
  * Detailed copyright and licensing information can be found
  * in the doc/COPYRIGHT and doc/LICENSE files which should be
  * in the doc/COPYRIGHT and doc/LICENSE files which should be
Line 49: Line 26:
  * @subpackage ...  
  * @subpackage ...  
  *
  *
  * @copyright (c)2000-2008 Ivo Jansch
  * @copyright (c)2000-2010 Ivo Jansch
  * @copyright (c)2000-2008 Ibuildings.nl BV
  * @copyright (c)2000-2010 Ibuildings.nl BV
  * @license http://www.achievo.org/atk/licensing ATK Open Source License
  * @license LGPL - http://www.atk-framework.com/licensing  
  *
  *
  * @version $Revision$
  * @version $Revision$
Line 57: Line 34:
  */
  */
</syntaxhighlight>
</syntaxhighlight>
== Class comments ==
There should be an informative head preceding the class declaration.
<syntaxhighlight lang="php">
  /**
  * Class description
  *
  * @author Name <email address>
  * @package atk
  * @subpackage
  */
  class Something
</syntaxhighlight>
== Function/method comments ==
Don't state the obvious in documentation. Explain usage, and why the function exists, and/or how it works (if relevant)
<syntaxhighlight lang="php">
  /**
  * Function description
  * @param type $name description
  * @return type description
  */
  private function _something($name)
</syntaxhighlight>
== Variable comments ==
<syntaxhighlight lang="php">
  /**
  * Variable description
  * @var type
  */
  private $m_something
</syntaxhighlight>
= Including Code =
Including files can be done with include, require, include_once and require_once. Understand the differences and use each appropriately.
= Control Structures =
<syntaxhighlight lang="php">
if ((condition1) || (condition2))
{
  action1;
}
elseif ((condition3) && (condition4))
{
  action2;
}
else
{
  defaultaction;
}
</syntaxhighlight>
The control structures will have a white-space between the reserved word and the
opening parenthesis.
<syntaxhighlight lang="php">
switch (condition1)
{
  case 1:
    action1;
    break;
  case 2:
    action2;
    break;
  default:
    defaultaction;
}
</syntaxhighlight>
Use opening and closing brackets at all times, even when there's only one line of code following your statement.
= 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.
<syntaxhighlight lang="php">
$var = foo($bar, $other, $last);
</syntaxhighlight>
Note the spaces surrounding the operator. This is done for improved readability.
The following is allowed (but not required) in case multiple assignments are done (use spaces, not tabs).
<syntaxhighlight lang="php">
$short        = foo($bar);
$longVariable = foo($other, $last);
</syntaxhighlight>
= Function bodies =
<syntaxhighlight lang="php">
  public function fooFunction($arg1, $arg2='')
  {
    $var = false;
    if (condition)
    {
      statement;
    }
    return $val;
  }
</syntaxhighlight>
The name of the function uses an uppercase for the first letter as every word except the first.
= Naming conventions =
In general, use short, but descriptive names. 
== 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").
Global functions (not in a class) should be avoided. Valid global funtions are 'convenience wrappers' for often-used class methods. E.g. atkText() is valid shorthand for atkLanguage::text().
Global functions should always be prefixed with a product or project-prefix.
Private and protected class methods will be preceded by an underscore.
(_). Even when declared explicitly as private, this should be used, so it is clear immediately from a piece of code if it is relying on private methods.
_sort(), _initTree().
== Constants ==
Constants will go always in capital letters, with underscores separating words.
  AF_HIDE_LIST
== Variables ==
=== General variables ===
Variable names should be short but descriptive. All words except the first start with uppercase. Preferably, variable names only contain one word. Static variables should be prefixed with $s_.
<syntaxhighlight lang="php">
$i
$header
$footerWidth
static $s_counter
</syntaxhighlight>
=== Class members ===
Class members follow the rules for general variables. Private and protected variables should be prefixed by an underscore ('_'). The older 'm_' prefix for member variables is allowed, but discouraged.
=== Global Variables ===
Global variables are strongly discouraged. If unavoidable, use $g_ as a prefix to identify them as globals.
== Predefined Values ==
Predefined PHP values true, false and null will go written always in small letters.
== Database Fields and Tables Naming ==
=== Table names ===
Table names are in lowercase, and singular ('project' instead of 'projects'). Table names consisting of multiple words are concatenated (no underscores).
In intermediary tables, an underscore can be used to indicate what tables the intermediary table links.
<sql>
  project
  projectdocument
  activity
  project_activity
</sql>
=== Fieldnames ===
Fieldnames are lowercase.
= 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
with multiple conditions, use parenthesis to avoid and/or confusion.
Bigger statements can be spread over multiple lines and indented.
<sql>
SELECT
  *
FROM
  users
WHERE
  registered = 'y') AND
    ((user_level = 'administrator') OR
      (user_level = 'moderator'))
</sql>
Avoid '*' in select statements. 'select *' is bad, 'select tablename.*' is better but still not optimal, 'select tablename.columname' is ideal.

Latest revision as of 09:26, 11 March 2011

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.

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.

Naming conventions

We follow the Zend Framework naming conventions for classes, with the following exceptions:

  • 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.
  • Nodes are considered business entities and are named in common english in all-lowercase, for example:
class employee extends atkMetaNode

Comments

Header for ATK

For ATK scripts, the file header is: 

/**
 * This file is part of the ATK Framework 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
 * @subpackage ... 
 *
 * @copyright (c)2000-2010 Ivo Jansch
 * @copyright (c)2000-2010 Ibuildings.nl BV
 * @license LGPL - http://www.atk-framework.com/licensing 
 *
 * @version $Revision$
 * $Id$
 */
Retrieved from "https://atk-framework.com/index.php?title=Coding_Guidelines&oldid=19618"