Standard de codage

Ce document décrit les règles et recommandations pour le développement de Nette. Lorsque vous contribuez au code de Nette, vous devez les respecter. La manière la plus simple de le faire est d'imiter le code existant. L'objectif est que tout le code ait l'air d'avoir été écrit par une seule personne.

Le standard de codage Nette correspond au PSR-12 Extended Coding Style avec deux exceptions principales : il utilise des #Tabulations au lieu d'espaces pour l'indentation et utilise PascalCase pour les constantes de classe.

Règles générales

• Chaque fichier PHP doit contenir declare(strict_types=1)
• Deux lignes vides sont utilisées pour séparer les méthodes pour une meilleure lisibilité.
• La raison de l'utilisation de l'opérateur shut-up doit être documentée : @mkdir($dir); // @ - le répertoire peut exister.
• Si un opérateur de comparaison faiblement typé est utilisé (c.-à-d. ==, !=, …), l'intention doit être documentée : // == accepter null
• Vous pouvez écrire plusieurs exceptions dans un seul fichier exceptions.php.
• La visibilité des méthodes n'est pas spécifiée pour les interfaces, car elles sont toujours publiques.
• Chaque propriété, valeur de retour et paramètre doit avoir un type spécifié. Inversement, pour les constantes finales, nous ne spécifions jamais le type, car il est évident.
• Les guillemets simples doivent être utilisés pour délimiter les chaînes, sauf lorsque le littéral lui-même contient des apostrophes.

Conventions de nommage

• N'utilisez pas d'abréviations, sauf si le nom complet est trop long.
• Utilisez des majuscules pour les abréviations de deux lettres, pascal/camel pour les abréviations plus longues.
• Utilisez un nom ou une expression nominale pour le nom de la classe.
• Les noms de classe doivent contenir non seulement la spécificité (Array), mais aussi la généralité (ArrayIterator). Les attributs du langage PHP font exception.
• Les constantes de classe et les énumérations doivent utiliser PascalCaps.
• Les interfaces et les classes abstraites ne doivent pas contenir de préfixes ou de suffixes comme Abstract, Interface ou I.

Wrapping et accolades

Le standard de codage Nette correspond à PSR-12 (resp. PER Coding Style), le complète ou le modifie sur certains points :

• les fonctions fléchées s'écrivent sans espace avant la parenthèse, c.-à-d. fn($a) => $b
• une ligne vide n'est pas requise entre différents types d'instructions d'importation use
• le type de retour de la fonction/méthode et l'accolade ouvrante sont toujours sur des lignes séparées :

	public function find(
		string $dir,
		array $options,
	): array
	{
		// corps de la méthode
	}

L'accolade ouvrante sur une ligne séparée est importante pour la séparation visuelle de la signature de la fonction/méthode du corps. Si la signature est sur une seule ligne, la séparation est claire (image de gauche), si elle est sur plusieurs lignes, dans PSR les signatures et le corps se confondent (au milieu), tandis que dans le standard Nette, ils restent séparés (à droite) :

Blocs de documentation (phpDoc)

Règle principale : Ne dupliquez jamais aucune information dans la signature, comme le type de paramètre ou le type de retour, sans valeur ajoutée.

Bloc de documentation pour la définition de classe :

• Commence par la description de la classe.
• Suivi d'une ligne vide.
• Suivi des annotations @property (ou @property-read, @property-write), une par une. La syntaxe est : annotation, espace, type, espace, $nom.
• Suivi des annotations @method, une par une. La syntaxe est : annotation, espace, type de retour, espace, nom(type $param, …).
• L'annotation @author est omise. La paternité est conservée dans l'historique du code source.
• Les annotations @internal ou @deprecated peuvent être utilisées.

/**
 * Partie de message MIME.
 *
 * @property string $encoding
 * @property-read array $headers
 * @method string getSomething(string $name)
 * @method static bool isEnabled()
 */

Un bloc de documentation pour une propriété, qui ne contient que l'annotation @var, doit être sur une seule ligne :

/** @var string[] */
private array $name;

Bloc de documentation pour la définition de méthode :

• Commence par une brève description de la méthode.
• Pas de ligne vide.
• Annotations @param sur des lignes individuelles.
• Annotation @return.
• Annotations @throws, une par une.
• Les annotations @internal ou @deprecated peuvent être utilisées.

Chaque annotation est suivie d'un espace, à l'exception de @param, qui est suivie de deux espaces pour une meilleure lisibilité.

/**
 * Trouve un fichier dans le répertoire.
 * @param  string[]  $options
 * @return string[]
 * @throws DirectoryNotFoundException
 */
public function find(string $dir, array $options): array

Tabulations au lieu d'espaces

Les tabulations présentent plusieurs avantages par rapport aux espaces :

• la taille de l'espacement peut être personnalisée dans les éditeurs et sur le web
• elles n'imposent pas au code la préférence de l'utilisateur en matière de taille d'indentation, de sorte que le code est plus portable
• elles peuvent être écrites en une seule touche (partout, pas seulement dans les éditeurs qui transforment les tabulations en espaces)
• l'indentation est leur but
• elles respectent les besoins des collègues malvoyants et aveugles

En utilisant des tabulations dans nos projets, nous permettons une personnalisation de la largeur, ce qui peut sembler superflu pour la plupart des gens, mais est essentiel pour les personnes ayant une déficience visuelle.

Pour les programmeurs aveugles qui utilisent des afficheurs braille, chaque espace représente une cellule braille. Ainsi, si l'indentation par défaut est de 4 espaces, une indentation de 3ème niveau gaspille 12 précieuses cellules braille avant même le début du code. Sur un afficheur de 40 cellules, qui est le plus couramment utilisé sur les ordinateurs portables, cela représente plus d'un quart des cellules disponibles gaspillées sans aucune information.