iGalerie

Documentation d'iGalerie 2

Conventions de codage

Le code d'iGalerie respecte un ensemble de règles bien précises qu'il convient de connaître et de respecter si vous souhaitez ajouter ou modifier du code. Les règles qui suivent concernent avant tout le code PHP mais s'appliquent également dans leur majorité au code Javascript.

Règles d'écriture

Identation

L'indentation doit être composée de tabulations de taille égale à 4 espaces.

Longueur de ligne

La ligne de code est limitée à 100 caractères, indentation comprise.

Accolades

Toujours mettre des accolades, même quand cela n'est pas indispensable.

Correct :

if ($condition) { instruction(); }

Pas correct :

if ($condition) instruction();
Style d'écriture

Le style d'écriture utilisé est le format BSD.

Exemple :

private function _example($album, $image, $db_infos)
{
    if ($db_infos['image_status'] == 1)
    {
        $updade_infos['a_size'] += $diff_filesize;
    }
    else
    {
        $updade_infos['d_size'] += $diff_filesize;
    }
}

D'une manière générale, le code doit être propre, bien organisé et aéré.

Guillemets

Utiliser en priorité des guillemets simple pour délimiter les chaînes de caractères.

Correct :

$variable = 'example';

Pas correct :

$variable = "example";
Classes

Utiliser le caractère de soulignement (_) comme premier caractère des noms d'attributs et de méthodes privées ou protégées.

Template

Utiliser une syntaxe qui rend plus explicite la nature des fins de blocs par des mots-clés : endif, endwhile, endfor, endforeach, endswitch.

Exemple :

<ul>
    <?php foreach ($books as $book) : ?>
        <li><?php echo $book; ?></li>
    <?php endforeach; ?>
</ul>
Tags PHP

L'utilisation des tags <?php et ?> est obligatoire et seuls ces tags sont autorisés.

Commentaires

Les commentaires sont écrits au format phpdoc.

Si une fonction ou une méthode ne retourne rien, indiquer @return void.

Pour les éléments @param, @return, etc. il faut placer le texte à la ligne avec une tabulation, comme sur cet exemple :

/**
 * Envoi direct des images.
 *
 * @param array $add_images
 *    Nom de fichiers des images.
 * @param string $cat_path
 *    Chemin de l'album destination.
 * @return void
 */

Les commentaires doivent être écrit en français et être constitués de phrases commençant par une majuscule et se terminant par un point.

Enfin, les commentaires dièses (#) sont interdits. Pour toute autre portion de code non concernée par la PHPDoc, il faut utiliser le double slash (//), et ne jamais mettre de commentaire sur la même ligne que le code lui-même.

Correct :

// Commentaire.
$var = 'example';

Pas correct :

$var = 'example'; // Commentaire.

La seule exception acceptée concerne les commentaires indiquant la prise en compte d'un bug :

$value = ($value == 'i:1;') ? '' : $value;	// fix IE7.0 Vista

Règles de nommage

Les noms des variables, constantes, fonctions, attributs, méthodes et classes doivent respecter une logique de nommage.

Les noms de variables et de fonctions doivent être écrits en minuscule avec le caractère souligné comme séparateur de mots.

Les noms de constantes doivent être écrits en majuscule avec le caractère souligné comme séparateur de mots.

Enfin, les noms de classes, d'attributs et de méthodes doivent utiliser la convention lowerCamelCase.

Voici un tableau résumant ces règles de nommage par des exemples :

Élément Exemple
variable $categories_id
constante CONF_GALLERY_PATH
fonction extract_request()
attribut $getReport
méthode getAlbums()
classe tplCategory

Par ailleurs, les noms de tous ces éléments doivent toujours être écrits en anglais.

Dernière modification : 15/01/2011