Général
Balises PHP
N’utiliser que les balises PHP complètes, les balises courtes pouvant rentrer en conflit avec d’autres langages.
<?php
$phpCode;
?>
Indentation
Note : la norme initiale précisait 3 espaces, à cause d'une vieille habitude de Gérald. Elle avait été changée à 4 espaces récemment. Toutefois, à des fins d'harmonisation avec les pratiques courantes, nous recommandons aujourd'hui l'utilisation de tabulations.
L’indentation initiale d'une ligne est d'une tabulation, par exemple (les tabulations sont représentées par "»") :
Cependant, si à des fins de présentation, vous voulez réaliser des alignements, utilisez uniquement des espaces pour l'alignement. Par exemple (les tabulations sont représentées par "»" et les espaces par "°"):
<?php
$monTableAssoc = array(
» "uneClefCourte"°°°°°=> "uneValeur",
» "uneClefPlusLongue"°=> "uneAutreValeur"
);
?>
Ainsi votre alignement sera respecté quelque soit l'indentation, tout en laissant à chacun la possibilité de choisir la largeur d'indentation qu'il préfère (et aussi de "désindenter" avec une simple pression sur Suppr).
Configurer Eclipse pour cette norme
Si vous utilisez l'IDE Eclipse PDT, il est possible de configurer celui ci pour respecter facilement cette norme.
1) Cliquez sur Windows/Preferences.
2) Allez dans la section PHP/Formatter. Sélectionnez la valeur "Tabs" pour l'option "Tab policy".
2) Allez dans la section General/Editors/Text Editors. Assurez-vous que la case "Insert spaces for tabs" est décochée. Vous pouvez saisir la valeur qui vous convient pour "Displayed Tab Width", cela n'affecte que l'affichage.
Notez que le raccourci Ctrl+Shift+F formatera votre code correctement (pour les formats reconnus).
Encodage
Le jeu de caractères à utiliser pour tous les fichiers sources est l'UTF-8.
Astuce : Si vous utilisez l'IDE Eclipse PDT, il est possible de configurer le projet pour utiliser l'UTF-8 par défaut pour tous les fichiers. Cliquez sur Project/Properties puis sur l'option "Resource". Dans le cadre "Text file encoding", sélectionner l'option "Other" et utilisez le menu déroulant pour sélectionner "UTF-8".
Configuration PHP
Lorsque vous développez, pensez à bien activer toutes les messages PHP. Vérifiez les paramètres error_reporting et display_errors
display_errors = On
Tous messages d'erreurs (y compris les notices) doivent être pris en compte par le code.
Règles de nommage
Classes
En un coup d'oeil
<?php
/**
* @package PackageName
* @subpackage SubPackageName
* @author Croës Gérald
* @copyright Infos de copyrights
* @link Si lien il y a
* @licence Lien sur la licence choisie
*/
/**
* Objectif de la classe
*
* Une description plus longue de la classe si nécessaire
*
* @package PackageName
* @subpackage SubPackageName
*/
class MyClass {
/**
* Constantes en majuscules
*/
const UNE_CONSTANTE = 1;
/**
* foo sert à ça
*
* @var string
*/
public $foo;
/**
* otherFoo sert à ça
*
* @var int
*/
public $otherFoo;
/**
* C'est une variable protégée qui sert à ça
*
* @var ressource
*/
protected $_protectedFoo;
/**
* C'est une variable privée qui sert à ça
*
* @var ressource
*/
private $_privateFoo;
/**
* Méthode public qui fait quelquechose
*
* Alors en fait c'est assez compliqué ce qu'elle fait, voici
* donc une description longue de son rôle
*/
public function fooFunction () {
doSomething ();
}
/**
* Méthode public qui fait quelquechose
*
* @param string $pFooParam pFooParam sert à ça
* @param boolean $pIsFooParam2 Indique quelquechose (par défaut true)
* @return boolean Si on peut continuer (true) ou pas (false)
*/
public function otherFooFunction ($pFooParam, $pIsFooParam2 = true) {
$this->doSomething ();
return canDoSomethingElse ();
}
/**
* Méthode qui fait quelquechose
*/
private function _privateFunction () {
$this->doSomething ();
doSomethingElse ();
}
/**
* Voici une méthode statique
*
* @param string $pMyVar Ma variable en paramètre
* @throws CopixException
*/
static public function myStatic (&$pMyVar) {
$myValue = array (0 => 'oui', 1 => 'non');
$myReference = &$myValue;
if (count ($myReference) > 0) {
throw new CopixException ('Syntaxe des exceptions');
}
if (!true) {
throw new CopixException (_i18n ('copix:copix.not.true'));
}
self::myStatic ($pMyVar);
}
}
?>
Nom
Généralités
Tous les mots qui composent le nom d'une classe commencent par une majuscule. Les fichiers portent l'extension ".class.php" et sont en minuscule.
Services
Les classes de services se nomment ServicesRole et sont dans un fichier servicesrole.class.php. On les instancie via la CopixClassesFactory avec la syntaxe
$service = CopixClassesFactory::create ('module|ServicesRole');
//ou
$service = _class ('module|ServicesRole');
Cas particulier des acronymes
Les acronymes sont écrits en majuscules.
Exemple
class HTMLHeader {}
class XMLViewer {}
class HTTPResponse {}
Méthodes
Le premier mot du nom d'une méthode commence par une minuscule. Les mots suivants commencent par une majuscule.
class HTMLViewer {
function doSomething () {}
function getSomething () {}
function getSomethingElseForTheSakeOfTheExample () {}
}
Les acronymes, en fonction de leur position dans le nom de la fonction, sont écrits tout en minuscule ou tout en majuscule.
class XMLParser {
function htmlView () {}
function xmlCheck () {}
function getXMLNode () {}
function getHTMLView () {}
function setValueInXML () {}
}
Les méthodes protégées et privées commencent par un underscore "_"
class Foo {
private function _privateMethod () {}
protected function _protectedMethod () {}
public function publicMethod () {}
}
Les paramètres des méthodes suivent les mêmes règles que les attributs de classe, à l'exception qu'ils commencent par la lettre "p".
class MaClass {
public function maMethode ($pParametre1, $pParametre2, $pParametreFacultatif = true) {
}
}
Attributs
Les attributs de classe suivent les mêmes règles que les noms de méthodes (premier mot en minuscule, les mots suivants commencent par une majuscule).
class HTMLStuff {
private $_privateData;
protected $_xmlValue;
protected $_formatHTML;
public $xmlCheck;
public $isHTML;
}
Scripts de bases de données
Scripts MySQL
Lors de la création de tables MySQL ne jamais préciser le moteur à utiliser (option ENGINE) afin d'utiliser le moteur par défaut configuré au niveau du serveur/de la base de données.
En revanche, toujours préciser l'encodage à utiliser pour les tables (option CHARACTER SET). Sauf besoin exceptionnel, l'encodage à utiliser est l'UTF-8.
Il convient également de mettre tous les noms de table et de champs entre backquotes (`), afin d'éviter les conflits avec des mots réservés.
Exemple:
CREATE TABLE `copixconfig` (
`id_ccfg` varchar(255) NOT NULL default '',
`module_ccfg` varchar(255) NOT NULL default '',
`value_ccfg` varchar(255) default NULL,
PRIMARY KEY (`id_ccfg`)
) CHARACTER SET utf8;