Introduction :

Rentrer dans le code de quelqu’un ou tout simplement faire un code qui sera compréhensible pour tout le monde n’est pas toujours facile !

Voici des règles a respecter sur le développement de nk et qui sont de très bonnes choses à savoir pour tous développeur. Et surtout, des actions à mettre en place par chacun afin d’augmenter la qualité du code PHP et donc augmenter la qualité de nuked-klan.

RECOMMANDE : Vous pouvez ignorer cette partie si vous utilisez le plugin "EditorConfig" disponible à cette adresse : editorconfig.org

• Etre stocké comme du texte ASCII;
• Utiliser le jeux de caractères UTF-8;

Editeur :

• Sublime Text 2 : Preferences -> Settings -- Default -> "default_encoding": "UTF-8",

• Etre formaté Unix;

Editeur :

• Sublime Text 2 : Preferences -> Settings -- Default -> "default_line_ending": "unix",

• Les lignes doivent finir uniquement par un retour à la ligne (LF).

Les retours à la ligne sont représentés par l'ordinal 10, l'octal 012 et l'hexadécimal 0A. N'utilisez par les retours « carriage » (CR) comme le font les Macintosh ou les combinaisons retour « carriage » / retour à la ligne (CRLF) comme le fait Windows.

• Il ne doit y avoir qu'un seul retour à la ligne après la fermeture du tag PHP ?>.

RECOMMANDE : Vous pouvez ignorer cette partie si vous utilisez le plugin "EditorConfig" disponible à cette adresse : editorconfig.org

• Tabulations remplacés par 4 espaces;

Editeur :

• Sublime Text 2 : Preferences -> Settings -- Default ->

    // The number of spaces a tab is considered equal to
    "tab_size": 4,

    // Set to true to insert spaces when tab is pressed
    "translate_tabs_to_spaces": true,

    // If translate_tabs_to_spaces is true, use_tab_stops will make tab and
    // backspace insert/delete up to the next tabstop
    "use_tab_stops": true,

    // Set to false to disable detection of tabs vs. spaces on load
    "detect_indentation": true,

Cette prochaine version sera codée entièrement en type de nommage lowerCamelCase.

Exemple

• Les dossiers (Includes => includes)
• Les fichiers (fatal_errors.php => fatalErrors.php)
• Les variables ($max_download => $maxDownload)
• Les méthodes ( function banip() => function banIp() )

Hormis les dossiers “extras” du type INSTALL et RESTDIR qui sont les dossiers qui requièrent l’attention de l’utilisateur à l’installation.

• Nommage des classes CSS de modules

Toutes les classes des fichiers CSS des modules doivent être préfixées du nom du module en minuscule.

Ex: Pour le module Team, les classes seront : “teamPlayersInfos”

Les noms des classes doivent être parlant et ne doivent contenir que des caractères [a-z][A-Z]. Il doivent toujours commencer par "NK_" et éviter les abréviations. Elles doivent être placés dans /includes/libs.

Exemple :

<?php
/**
 * Light template library.
 * @name NK_tpl
 * @desc Custom class for include template
 */
class NK_tpl {
//code
}
?>

De même que pour les classes, vos noms de fonctions et méthodes ne doivent contenir que des caractères [a-z][A-Z] et le nom doit être explicite afin de savoir ce que fait la fonction à partir de son nom.

La notation lowerCamelCase doit être utilisée : Le nom de la fonction doit commencer par une minuscule. Si le nom est composé de plusieurs mots, chaque première lettre des mots doit être mise en majuscule.

Exemple :

<?php
function doDownload() {
    // code
}
?>

Les fonctions dites utilitaires seront préfixés des lettres "nk".

Exemple :

<?php
function nkDebug() {
    // code
}
?>

Les variables respectent les mêmes règles que les fonctions et méthodes. Les noms de variables comme $i sont déconseillés en dehors de petite boucles.

Pour faciliter la lisibilité et la maintenance, il faut stocker la requête SQL dans une variable avant de l’exécuter.Après exécution, la direction die (logError()); sera utilisée pour les logs (erreurs,...).

• $dbs -> pour les select
• $dbi -> pour les insert
• $dbu -> pour les update
• $dbd -> pour les delete
• $dbe -> pour l'execution (mysql_query)
• $dbc -> pour un count (mysql_num_rows)

Exemple :

<?php
$dbsForumCat = 'SELECT id, nom 
                FROM ' . FORUM_CAT_TABLE . ' 
                ORDER BY ordre, nom';
$dbeForumCat = mysql_query($dbsForumCat) or die (logError());
$dbcForumCat = mysql_num_rows($dbeForumCat);
?>

Une constante doit être nommée avec des caractères alphanumériques en uppercase. Chaque mot la composant doit être séparé par des underscore "_".

Exemple :

// Ok
NB_MAX_FILES
// Ko
NB_MAXFILES
// KO
_NB_MAX_FILES

Les fichiers PHP doivent commencer et terminer avec les balises PHP "". L’utilisation des autres balises de déclaration du code PHP sont à proscrire.

Les accolades doivent respecter cette nomenclature.

Exemple :

<?php
public function nkContentTag() {
    // code
}
function nkDebug() {
    // code
}
for (int i = 0; i < 5; i++) {
    // code
}
?>

Accolades obligatoires même si la structure n’a qu’une ligne.

Exemple :

<?php
if ($casDeTest === TRUE) {
    // code
}
?>

Toute variable déclarée doit l’être de la façon suivante.

Exemple :

<?php
$maVariable = 'valeur';
?>

Un espace doit être présent avant et après le signe "=" (attention aux cas particuliers).

Les instructions de contrôles doivent avoir un espace entre l’instruction et la parenthèse ouvrante. Un espace autour des opérateurs de comparaison, d’affectation, arithmétique.

Exemple :

<?php
$a = 0;
$i == 2;
$b += $c;
?>

Lors du passage de plusieurs variables à une fonction/méthode, veuillez mettre un espace après chaque virgule.

Exemple :

<?php
maFonction($val1, $val2, $val3);
?>

Une ligne vide entre chaque méthode.

Exemple :

<?php
    public function nkContentTag() {
         // Code Méthode 1
    }
    
    public function nkDisplayError() {
        // Code Méthode 2
    }
?>

Chaque fichier qui contient du code PHP et chaque classe doit avoir une entête contenant au minimum ces balises.

• Description du fichier
• Version du cms
• Link du cms
• License du cms
• Copyright du cms

Exemple :

<?php
/**
*   [file description]
*
*   @version 1.8
*   @link http://www.nuked-klan.org Clan Management System 4 Gamers NK CMS
*   @license http://opensource.org/licenses/gpl-license.php GNU Public License
*   @copyright 2001-2013 Nuked Klan 
*/
?>

Les variables de classes doivent être commentées avec les paramètres suivants.

• Description
• Type

Exemple :

<?php
class MyClass {
	/**
	* Name of customer
	*@var string
	*/
	public $customerName;
}
?>

Chaque méthode doit être documentée avec au minimum les paramètres.

• Description
• Tous les arguments
• Valeurs de retour possibles

Exemple :

<?php
/**
* Description courte de la méthode
*
* @param integer|string $iCustomerID ID du customer
* @return object Retourne l'objet Customer correspond à l'ID reçu
*/
?>

Il est recommandé de commenter des blocs de code complexes à l’aide d’une ligne d’explications.

Exemples :

<?php
// Commenter ici la boucle complexe
for ($object as $value){
	// ...
}
?>

L’anglais doit être utilisé dans le nommage des variables, classes, méthodes ainsi que lors de l’ajout de commentaire. Pensez à l’Open Source et au partage de connaissance.

Ne pas **minimiser ** vos fichiers JS. Sachez que pour le développement, on a besoin d’avoir un code lisible (et pas tout sur une seule ligne !), donc laisser la réduction des lignes de côté.

Plus le nom de vos variables est court, plus rapide seront vos scripts. Par contre, mieux vaut un nom de variable un peu plus long et compréhensible qu’un nom de variable abrégé ne donnant aucune information quant à son contenu.

L’usage des double quotes est plus courant que celui des simples pour manipuler des chaines de caractères. La différence majeure entre les deux est l’interprétation des potentielles variables quelles peuvent contenir. L’utilisation des simples quotes est beaucoup plus rapide que celle des doubles.

Veuillez utiliser la virgule à la place du point pour la concaténation de variables lors d’un echo. Echo est une fonction qui peut attendre plusieurs paramètres. L’utilisation du point va d’abord lancer une opération de concaténation avant le passage à la fonction echo.

Exemple :

<?php
// Fonctionne mais
echo 'test est' . $maVar1;
// Ceci est plus performant
echo 'test est',  $maVar1;
?>

L’opérateur ternaire est souvent utilisé par commodité d’écriture. Malheureusement ce dernier est plus lent qu’une condition if/else. Ne pas utiliser l'opérateur ternaire.

N’utilisez pas de fonction comme count() ou sizeOf() (alias de count) dans des boucles. Préférez déclarer une nouvelle variable avant le for qui contiendra le nombre d’élements de votre tableau count($myArray) afin de l’utiliser dans le for.

Exemple :

<?php
$sizeArray = count($myArray);
for ($i = 0; $i < $sizeArray; $i++) ..
// la méthode count est appellée à chaque itération
for ($i = 0; $i < count($myArray); $i++) ..
?>

Si vous devez comparer 2 variables entre-elles en sachant qu’elles sont de même type, il est préférable d’utiliser l’opérateur ‘===’. Ce dernier vérifiera la valeur sans avoir à les convertir et prendra ainsi moins de temps.

Evitez d’utiliser les fonctions utilisant les expressions régulières lorsque vous n’en avez pas l’utilité.

Pensez à mettre en forme votre code afin de le rendre plus visible par autrui.

Une ligne de code trop longue peut être mise en forme de la manière suivante.

Exemple :

<?php
// Les requetes ne doivent plus être ecrite comme ça
$dbsForumCat = 'SELECT id, nom FROM ' . FORUM_CAT_TABLE . ' ORDER BY ordre, nom';
$dbeForumCat = mysql_query($dbsForumCat) or die (logError());
$dbcForumCat = mysql_num_rows($dbeForumCat);

// Mais comme ceci
$dbsForumCat = 'SELECT id, nom 
                FROM ' . FORUM_CAT_TABLE . ' 
                ORDER BY ordre, nom';
$dbeForumCat = mysql_query($dbsForumCat) or die (logError());
$dbcForumCat = mysql_num_rows($dbeForumCat);

// Une longue condition if
if ($myVar1 == 'valeur' && $myVar2 == 'valeur' && $myVar3 != 'valeur' && ....) {
	// code
}
// peut être remplacé par
if ($myVar1 == 'valeur'
    && $myVar2 == 'valeur'
    && $myVar3 != 'valeur'
    ...){
	// code
}
?>

Aligner les variables / valeurs entre-elles

Exemple :

<?php
$maVar1     = 'toto';
$myTable1   = array();
$myCustomer = new Customer();
?>

Limitez l’utilisation des echo lorsque cela est possible, par exemple dans une boucle.

Exemple :

<?php
// KO
$countMyArray = count($myArray);
for ($i = 0; $max = $countMyArray; $i++){
	echo $myArray[$i], '';
}
// OK
$countMyArray = count($myArray);
for ($i = 0; $max = $countMyArray; $i++){
	$string .= $myArray[$i]."";
}
echo $string;
?>

PHP permet d’inclure des fichiers avec quatre instructions distinctes :

• include
• include_once
• require
• require_once

Ces quatre versions correspondent en réalité aux combinaisons de deux variantes :

• require déclenche une erreur et arrête le programme si le fichier inclus n’est pas trouvé. include se contente de provoquer un avertissement.
• les versions «_once » gèrent les risques d’inclusions multiples. Avec include_once (comme avec require_once), PHP s’assure que chaque fichier n’est inclus qu’une seule et unique fois, même si plusieurs demandes sont faites.

Dans la pratique, on utilisera de préférence l’instruction require_once (sauf besoins spécifiques) car elle présente le maximum de garanties. Ces quatre instructions ne sont pas des fonctions. Il ne faut donc pas entourer de parenthèses le nom du fichier appelé.

Exemple :

<?php
// Instructions Ok
require 'conf.inc.php';
require_once 'conf.inc.php';
include '/includes/libs/NK_mySql.php';
include_once '/includes/libs/NK_mySql.php';
// Instructions Ko
require('conf.inc.php');
require_once('conf.inc.php');
include('nuked.php');
include_once('Includes/php51compatibility.php');
?>

Ces constantes doivent toujours être écrite en minuscule.

Les variables ne pouvant pas être ‘typée’ en PHP, vous pouvez si vous le souhaitez, utiliser une astuce de nommage de variables afin préciser le type de vos variables.

Rajoutez une simple lettre devant votre nom de variable.

• b -> boolean
• i -> integer
• d -> double
• s -> string
• a -> array
• m -> mixed
• o -> object
• r -> ressource

Exemple :

<?php
$bError = true;
$iCount = count($aCustomers);
// etc
?>