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

Blank Lines

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