Norme de codage PHP pour Voozanoo 4

Norme de codage pour les développements framework en PHP

Edit me

La norme de codage

Voici la norme de codage utilisée en PHP par l’équipe Framework. Il est conseillé de l’appliquer pour tous les développements Voozanoo pour assurer une homogénéité du code. Pour le noyau Voozanoo, elle doit être systématiquement appliquée.

Nommage des variables

On « Cast » les variables, pour indiquer leur type. La première lettre après le symbole $ est donc le type de la variable, ou m si le type est mixte ou indéterminé.

Le nom de la variable, à partir de la deuxième lettre, est en Camel Case et commence par une majuscule

$aList = array();
$sMyText = "texte";
$iInt = 5;
$mMixed = strpos( $sMyText, "value" );
$oProject = $this->GetProject();

Tabulations et indentations

Tabs and Indents

Caractères utilisés pour l’indentation : 4 espaces
Garder l’indentation sur les lignes vides : Non, on ne met pas d’espace sur les lignes vides

Espaces

Spaces

On ajoute des espaces dans les cas suivants pour plus de lisibilité :

Opérateurs :

Après la parenthèse ouvrante et avant la parenthèse fermante d’une fonction
Après la parenthèse ouvrante et avant la parenthèse fermante d’un if
Pareil pour les parenthèses de for, while, switch et catch
Autour des opérateurs d’assignement (=, +=, etc.)
Autour des opérateurs d’égalité (=, !=)
Autour des opérateurs logiques (&&, ǀǀ, etc.)
Autour des opérateurs relationnels (<, >, etc.)
Autour des opérateurs “Bitwise” (&, ǀ, ^)
Autour des opérateurs “Shift” (», «)
Autour du symbole de concaténation (.)
Assignement avec le mot clé declare

Avant les accolades

Avant l’accolade ouvrante des mots clés class, function, if, else, for, while, do, switch, try, catch et finally

function bar( $aParams ) {
	// code
}

Avant les mots-clés suivants :

else
while
catch
finally

if ( $bTest ) {
	// code
} else {
	// code
}

Blocs, accolades et parenthèses

Warpping and Braces

Les fonctions très courtes peuvent être écrites en une seule ligne :

function foo() { return 0; }

On met les accolades ouvrantes à la fin de la ligne de déclaration de la classe, de la fonction ou du namespace

namespace A {
	function foo() {
		// code
	}
}

On écrit tous les paramètres d’une fonction sur la même ligne que celle-ci

function bar( $sParam1, $sParam2, $sParam3 ) { // code }

Pareil pour les paramètres des constructeurs de ces fonctions
Lorsqu’on chaine les méthodes, on peut retourner à la ligne s’il y a trop de méthodes consécutives

$oCommitEnv = Core_Library_Account::GetInstance()->GetCurrentProject()
            ->ModelManager()
            ->Commit( $oCtx->get( 'oDataJson' ) );

Il faut toujours mettre les accolades pour les if, for, foreach même s’ils sont simples ou ne font qu’une ligne
On met les paramètres de ces derniers sur une seule ligne
Lorsqu’on définit un tableau, en le déclarant ou en le passant en paramètre, on peut tout à fait l’écrire en plusieurs lignes. On met alors les parenthèses ouvrantes et fermantes sur une seule ligne :

$aJsonReturn = array(
                'success' => true,
                'records' => array()
            );

Lignes blanches

On peut ajouter une ligne vide dans les circonstances suivantes :

Dans un bloc de code, pour séparer des traitements
Après une accolade ouvrante, par exemple pour une fonction vide

On ajoute systématiquement une ligne vide dans les cas suivants :

Après la déclaration d’un namespace ou un bloc de use
Avant et après une class
Pour séparer deux méthodes
Après une fonction
Juste avant un return, pour le séparer du code qui le précède, le cas échéant

PHPDocs

PHPDoc

Dans un bloc PHPDoc :

On aligne les paramètres / propriétés
On insère une ligne vide avant et après le bloc des paramètres
On aligne les descriptions des paramètres / propriétés

/**
 * This is a sample function to illustrate additional PHP formatter
 * options.
 *
 * @param        $one   The first parameter
 * @param int    $two   The second parameter
 * @param string $three The third parameter with a longer comment to illustrate wrapping.
 *
 * @return void
 * @author  MZZ
 * @license GPL
 */

Casse des mots réservés

Code Conversion

On convertit en lower case :

true / false
null
On utilise elseif, plutôt que de faire un else contenant un autre if
On ne met pas de virgule après le dernier élément d’un tableau

$x = array(
    0 => "zero",
    123 => "one two three",
    25 => "two five, no comma"
);

Automatisation de la norme de codage

Pour les utilisateurs de PHPStorm

Pour les utilisateurs de PHPStorm, il suffit d’importer ce fichier de configuration dans votre IDE pour automatiser l’application de toutes ces règles.

Pour cela, aller dans Settings/Preferences et choisir Code Style.

Pour les autres

Pour les développeurs qui n’utilisent pas PHPStorm, il est aussi possible d’importer ce fichier .editorconfig dans votre IDE, mais ce fichier comporte beaucoup moins de règles.

L’usage de PHPStorm est donc privilégié.