Manuel d'apprentissage
⁂
Annexe,
Conventions de codage et de nommage
Cette annexe présente les conventions de codages et de nommages utilisées Hoa.
Table des matières
- Introduction
- Fichiers, dossiers et encodage
- Visilité
- Espaces de nommage, classes, interfaces, méthodes etc.
- Toujours être explicite
- Coding style
- Accolades
Introduction
Les conventions de codages et de nommages sont essentielles pour qu'un projet ait une solidité et une uniformité qui facilite sa compréhension et sa maintenance. On peut pousser très loin les détails des conventions mais ce serait inutile et fastidieux. On préfère donner les traits généraux pour faire ressentir la philosophie derrière ces conventions.
Fichiers, dossiers et encodage
Le nom des fichiers et dossiers adoptent la notation
CamelCase, i.e. que les mots ne sont pas séparés
par des espaces mais la première lettre de chaque mots est mise en majuscule,
les autres en minuscules. Tous les noms commencent également par une
majuscule. Ainsi : Router, Http, XmlRpc
etc., sont des noms valides.
Il faut accorder une attention toute particulière à la
casse (différence entre les majuscules et minuscules),
notamment si les systèmes de fichiers y sont sensibles (comme par exemple
ext4, a contrario de HFS+). En effet,
cela peut être la source d'erreur lors de la portabilité d'un projet.
L'encodage des fichiers est obligatoirement Unicode, et uniquement sur 8 bits, i.e. UTF-8. Cela permet d'avoir des fichiers portables dans toutes les langues et sur tous les éditeurs, et permet d'éviter des conflits d'encodages/décodages. De plus, Unicode est compatible avec les jeux de caractères inférieurs, comme les normes ISO ou UCS.
Le caractère de fin de ligne est line feed
(0x0A ou \n). Une ligne a une taille de
80 caractères maximum. Les lignes vides (uniquement des
caractères blancs) sont interdites. Une tabulation est
constituée de quatre espaces.
Enfin, quand un fichier contient du PHP, la balise de
fermeture ?> est omise.
Visilité
La visibilité s'exprime au niveau du code à l'aide des intructions
public, protected et private. Cela ne
concerne que les méthodes. Les conventions de Hoa permettent de connaître la
visibilité des structures manipulées, et ce raisonnement peut s'appliquer à
d'autres structures que des méthodes.
Si le nom est préfixé par underscore (symbole « _ »),
alors la structure est protégée ou privée, i.e. qu'elle n'est pas publique.
Ainsi, une classe dont le nom est _Protocol ne devrait pas être
utilisée par l'utilisateur.
Néanmoins, on notera l'utilisation du conditionnel ici. En effet,
l'utilisateur ne devrait pas, mais il peut tout à fait ! Hoa aime la
philosophie adoptant le concept d'hackability (ou
bidouillabilité), qui permet à tout utilisateur de modifier le
comportement du système. C'est pourquoi la majorité des structures,
qui ne sont pas publiques, sont protégées, et rarement privées (sauf si cela
se justifie). De même, rares sont les structures marquées de l'instruction
final (i.e. qu'on ne peut plus les modifier). On rappelle que
ce n'est parce que le système peut être modifié qu'il est moins sûr. Une bonne
conception peut laisser des libertés tout en assurant une certaine
confiance dans le code.
Enfin, on peut rencontrer des structures avec une visibilité protégée mais avec un nom non préfixé. Cela indique que ce sera une méthode inévitable à l'utilisation (comprendre qu'on l'utilisera très régulièrement) lors d'une extension du système.
Espaces de nommage, classes, interfaces, méthodes etc.
Les espaces de nommages, les classes concrètes, les classes abstraites, les interfaces, les méthodes, les attributs et les variables adoptent tous la notation CamelCase. Tout ce qui n'est pas une variable (de classes, de méthodes ou de fonctions), une méthode ou une fonction, voient leur première lettre mise en majuscule. Ainsi :
namespace Foo\BarBaz\Qux {
class FooBar {
public $iAmPublic = null;
protected $iAmProtected = null;
public function iAmAMethod ( $iAmAParameter ) {
$iAmAVariable = null;
$_iAmADangerousVariable = null;
}
}
}
namespace {
function iAmAFunction ( ) { }
}Les interfaces sont souvent suffixées par
able. Même si ce n'est pas toujours correct (grammaticalement
parlant), ça peut être amusant ! Ainsi Structural,
Cryonicable, Viewable sont des noms d'interfaces
valides. Les interfaces peuvent également être rangées dans un espace de nom
qui porte le même nom que l'espace parent mais préfixé par I,
comme Hoa\Stream\IStream\In ou Hoa\Tree\ITree\Node,
lorsque le paquetage propose plusieurs interfaces de même niveau.
Les classes abstraites portent souvent le nom
Generic.
Enfin, les constantes seront toujours marquées en majuscules.
Toujours être explicite
Même si le nom d'une variable commence à être longue ou compliquée à écrire, on ne l'abrégera jamais ! On veut toujours être explicite dans le nom des variables, des constantes, des méthodes, des classes etc. Les éditeurs textes savent facilement auto-compléter le nom si celui devient compliqué à écrire. Cela évite d'avoir une mauvaise compréhension du code et de son objectif.
De même, on ne laissera jamais le langage décidé du comportement par défaut pour nous. C'est pourquoi, par exemple, on précisera toujours la visibilité.
Coding style
Un bon style de codage permet une lisibilité rapide et ainsi une bonne compréhension.
Accolades
Si un bloc ne contient pas plus d'une instruction, les accolades ne sont pas obligatoires. On respectera toujours cette règle. Ainsi :
if(/* condition */)
/* a lonely instruction */;
else {
/* an instruction */
/* another instruction */
}On remarquera le positionnement des accolades : l'accolade ouvrante se situe sur la même ligne que l'instruction, puis est suivie d'une ligne vide, et enfin l'accolade fermante seule sur une ligne.
Parenthèses
Les parenthèses sont présentes pour enlever des ambiguïtés dans le code. Mais ses ambiguïtés existent rarement pour l'être humain. Il n'est donc pas utile de mettre les parenthèses en avant. C'est pourquoi aucun espace n'est présent autour.
Alignement
Un code se lit horizontalement mais aussi verticalement. Ainsi, aligner son code pour former des colonnes quand cela est utile offre une bien meilleure lisibilité et compréhension :
$i = 0;
$short = 42;
$loongName = 53;
$foo = 'bar';