Coppermine Photo Gallery v1.5.x: Documentation et manuel

Règles de travail pour le codage

Public ciblé

Cette partie de la documentation n'est pas à destination des utilisateurs de Coppermine, mais uniquement pour les développeurs. Il n'y a pas d'aide pour ces chapitres, ils sont livrés tels quels.

Les utilisateurs finaux qui veulent modifier leur copie de Coppermine, sont encouragés à suivre ces règles eux aussi.

Objet

Comme Coppermine est un travail d'équipe, les membres de l'équipe qui contribuent doivent s'assurer que le code reste facile à lire, à comprendre et à maintenir. C'est pourquoi il y a ici un certain nombre de règles qu'il faut respecter lorsque l'on travaille sur le code source de Coppermine. Bien que cette partie de la documentation soit pour les membres de l'équipe de développement de Coppermine, les utilisateurs qui souhaitent contribuer avec leur code de quelque manière que ce soit sont priés de répéter ces règles autant que possible (si vous les comprenez totalement).

Les règles de codage de cette page ne sont pas gravées dans le marbre - si vous (en tant que membre de l'équipe de développement) trouvez pendant le développement, qu'une de ces règles doit être révisée ou changée, commencez un sujet sur le forum de discussion dédié au développement (dev board) pour en discuter.

Indentation

• Utilisez une indentation de 4 espaces sans tabulations. La plupart des éditeurs peuvent être configurés pour cela.
• N'hésitez pas à laisser des lignes vides entre les "sections logiques" du code, mais n'en utilisez pas de trop, l'ensemble deviendrait trop espacé

Encodage

Règles générales

• Dans les requêtes ou dans le code, mettez toujours un espace avant et après un opérateur

Code PHP

Formatage

• Le signe égal doit être aligné avec les éléments environnants
  
  Mauvais exemple:

  $pic_title = 'My picture';
  $album = 'lastup';
  $update_time = true;

  Bon exemple:

  $pic_title   = 'My picture';
  $album       = 'lastup';
  $update_time = true;

• Les tableaux à valeurs multiples ne doivent pas être déclarés sur une seule ligne. Ils ne peuvent être déclarés sur une seule ligne que s’ils ne contiennent qu'une seule valeur
• Toujours mettre une virgule après la dernière valeur dans la déclaration d'un tableau (array)
• Toujours aligner les doubles flèches d'un tableau sur une ligne, et il doit y avoir un espace simple après la flèche (avant la valeur)
• Chaque ligne dans la déclaration 'un tableau doit se terminer par une virgule
  
  Mauvais exemples:

  $foo = array('one', 'two', 'three');
  
  $bar = array(
  'one' => 1, 'two' => 3,
  'three' => 3
  );
  
  $multi = array('first' => 'one', 'second' => array('2'), 'third' => array('foo' => 'bar', 'hello' => 'world'));
          

  Bons exemples:

  $foo = array(
          'one',
          'two',
          'three',
         );
  
  $bar = array(
          'one'   => 1,
          'two'   => 2,
          'three' => 3,
         );
  
  $multi = array(
            'first'  => 'one',
            'second' => array('2'), // Comme il n'y a qu'une valeur dans le tableau, il peut être déclaré dans la même ligne
            'third'  => array(
                         'foo'   => 'bar',
                         'hello' => 'world',
                        ),
           );
          

• Utilisez echo à la place de print
• Utilisez des guillemets simples au lieu des guillemets doubles
  Mauvais:

  $foo_array["bla"] = "whatever";

  Bon:

  $foo_array['bla'] = 'whatever';

• N'utilisez pas d'espaces ni de majuscules dans les définitions associées aux tableaux
  Mauvais:

  $bla_array['foo Bar'] = 'some string';

  Bon:

  $bla_array['foo_bar'] = 'some string';

Structures de contrôle

cela inclue if, for, while, switch.

• Les éléments de contrôle doivent avoir un espace entre le mot-clé de contrôle et l'ouverture de la parenthèse, pour les distinguer des appels de fonctions
• Toujours utiliser les accolades, même dans les cas ou elles sont techniquement optionnelles - cela augmente la lisibilité et diminue le risque d'erreur lors de l'ajout de lignes
• Toujours commencer une nouvelle ligne pour l'ouverture ou la fermeture des accolades
  
  Mauvais exemple:

  if ($foo = 'bar') { echo 'Hello world'; }

  Mauvais exemple:

  if ($foo = 'bar')
  { echo 'Hello world'; }

  Bon exemple:

  if ($foo = 'bar') {
      echo 'Hello world';
  }

  Bon exemple:

  if ($foo = 'bar')
  {
      echo 'Hello world';
  }

Appel des fonctions

• Les fonctions doivent être appelées sans espaces entre le nom de la fonction, l'ouverture de la parenthèse, et le premier paramètre, des espaces entre les virgules et chaque paramètres, et sans espace entre le dernier paramètre, la parenthèse de fin et le point-virgule.
• Il doit y avoir un espace de chaque coté du signe égal utilisé pour assigner la valeur retournée par une fonction vers une variable. Dans le cas d'un bloc de tâches liées, plus d'espace doivent être insérés pour une plus grande lisibilité.

Définition des fonctions

• La définition des fonctions suit le modèle d'indentation 1TBC:

  <?php
  
  
  function fooFunction($arg1, $arg2 = '')
  {
      if (condition) {
          statement;
      }
      return $val;
  }
  
  
  ?>

• Les arguments avec une valeur par défaut doivent être en fin de liste des paramètres
• Il doit y avoir deux lignes vierges avant et après la déclaration de la fonctionT
• N'utilisez pas de fonctions qui n'existent pas dans PHP4.3 ou précédent (et n'utilisez pas non plus de fonctions qui ont été enlevées par la suite!) à moins de les définir pour leurs versions.

Balise de code PHP

• Utilisez toujours <?php ?> pour délimiter le code PHP, pas la version abrégée <? ?>, parce que la version longue fonctionne avec tous les paramétrages de serveur, alors que la version abrégée ne fonctionne pas partout.

Imbrication de HTML en PHP

Lorsqu'il y a plus d'une ligne d'HTML à afficher, la syntaxe Heredoc doit être utilisée au lieu de suspendre le processus PHP pour le rependre ensuite.

// PHP content here
if ($foo == $bar) {
	print <<< EOT
	<h1>Hello {$bla}</h1>
EOT;
}

// PHP content here
if ($foo == $bar) {
	?>
	<h1>Hello <?php echo $bla; ?></h1>
<?php
}

Fin de ligne

Pour afficher une fin de ligne dans la sortie HTML, utilisez la syntaxe heredoc ou utilisez la variable $LINEBREAK au lieu de coder des fins de lignes en dur dans le code.

N'oubliez pas de rendre la variable $LINEBREAK globale dans les fonctions.

echo '<h1>Hello world</h1>' . $LINEBREAK;
echo '<p>foo bar</p>';
}

echo "<h1>Hello world</h1>\n";
echo '<p>foo bar</p>';
}

Convention de nommage

• Les fonctions elles doivent être nommées en minuscules et utiliser l'annotation avec soulignement ex: function_name()
• Les variables Suivez la même convention (minuscule et utilisation du caractère de soulignement), par contre les variables globales doivent être en MAJUSCULES (ex: $CONFIG)
• Les superglobales (e.x. $_GET ou $_POST) doivent être sécurisées en utilisant Inspekt - référez vous au chapitre "Sécurisation des Superglobales en utilisant Inspekt"
• Les constantes doivent être définies en MAJUSCULES avec le caractère de soulignement comme séparateur de mots
• Les noms de fichiers doivent suivre la même convention d'utilisation du caractère de soulignement mais doivent être entièrement en minuscules
• Comme toujours, les noms descriptifs (pour les répertoires/fichiers/fonctions/variables/constantes) sont préférables au genre "$egYtesIopnfer". (sauf pour l'utilisation de compteurs, $i, etc.)

Requêtes dans la base de données

• Toujours libérer les ressources MySQL. (ainsi que les autres!)
• Dans les requêtes, toujours mettre en capitales les commandes : SELECT, INSERT, REPLACE, UPDATE, DELETE, etc. doivent toutes être en capitales
• Dans les requêtes, mettre toujours en capitales WHERE, AND, OR, LIMIT, FROM, JOIN, AS, ON, etc.
• Ne pas utiliser de noms de champs qui sont aussi des mots-clés de MySQL
• N'utilisez pas de fonctions Mysql qui ne sont pas utilisables avec MySQL 3.23.4 et précédent
• Optimisez toutes les requêtes pour MySQL 4, même si comme dit plus haut elles doivent fonctionner avec une version antérieure
• Utilisez LIMIT pour les requêtes à chaque fois que c'est possible
• LEFT JOIN est plus lent que le simple JOIN (ou les virgules) donc vous devez les éviter si possible
• Ce n'est pas messages as m, mais messages AS m, parce que AS est un mot clé MYSQL
• Lorsque vous faites un JOIN, la(les) table(s) reliées sont en premier dans la clause ON

Documentation

• Laissez la documentation correctement intégrée en haut des fichiers
• Laissez la documentation/les commentaires en tête de fichier avec une limite de 80 caractères
• Commencez chaque ligne avec une majuscule, et utilisez une grammaire correcte. (temps et le reste!)
• Il y a un sous-chapitre de la documentation du développeur qui traite de modifier la documentation - Merci d'en tenir compte
• Il y a des étapes particulières lors de l'ajout d'une option de configuration - Merci de vous référer au chapitre correspondant de la documentation.

Sortie HTML

• Toujours refermer les input, img, hr, et autres éléments qui ne peuvent rien contenir. (<tagname />)
• Coppermine est destiné à être conforme aux standards Web, Il faut donc toujours essayer de faire du code HTML et CSS valide. En particulier, les sorties vues par les visiteurs de la galerie (et par les robots des moteurs de recherche) doivent être totalement valides; les sorties uniquement vues par l'administrateur peuvent être moins strictes (Mais vous devez essayer de coder des sorties valides pour la partie administrateur malgré tout). Il y a une exception à cette règle de validité aux standards: si le code respectueux des standards brise les fonctionnalités de base des navigateurs principaux comme l'actuelle implémentation des objets embarqués qui ne sont pas respectueux des standards parce que IE5.x " ne respecte pas" le mode standard, il est acceptable de créer une sortie qui n'est pas valide au regard des standards. Dans ce cas, assurez vous de rendre attentif les autres en les dirigeant vers la section (problèmes connus de la documentation, mais au moins ajoutez quelques commentaires au code).
• Assurez vous qu'il n'y a pas de caractère &-(esperluettes) non échappés dans les sorties HTML. Les esperluettes doivent toujours être échappés comme ceci &amp;.
• Les caractères< et >-qui doivent s'afficher dans la sortie (qui ne composent pas de balises) doivent être codées ainsi &lt; et &gt;
• Laissez les attributs id uniques, et essayez de faire en sorte que id et name soient les mêmes si les deux sont définis

Balises images dans les sorties HTML

• Toujours mettre un attribut "alt" à tous les éléments images, même si le "alt" est vide
• L'attribut "border" est obligatoire - si vous l'oubliez, les vieux navigateurs vont afficher un cadre par défaut
• Si possible (par exemple si les dimensions d'une image sont connues) utilisez les attributs "width" et "height"
• N'utilisez pas le titre comme contenu du "alt", ne l'utilisez que si le titre est nécessaire (comme pour les icônes)
• Si vous avez besoin d'un gif aveugle; utilisez celui qui est toujours dans Coppermine (./images/spacer.gif) au lieu d'en créer un pour votre thème personnalisé, plugin ou autres

Liens dans les sorties HTML

• N'utilisez pas l'attribut "target", il est invalide. Utilisez <a href="http://exemple.com/" rel="external" class="external"> à la place. L'utilisateur final peut alors facilement utiliser JavaScript pour ouvrir le lien dans une nouvelle fenêtre s'il le souhaite.

Eléments de formulaires dans les sorties HTML

• Il est obligatoire d'utiliser des classes CSS particulières pour cetains éléments de formulaires:
  • <input type="text" class="textinput" />
  • <input type="submit" class="button" />
  • <input type="radio" class="radio" />
  • <input type="checkbox" class="checkbox" />
  • <select class="listbox" />

Balises dépréciées

Les balises HTML dépréciées comme <font> ne doivent pas être introduites dans Coppermine sans qu'il n'y ait une raison valide et documentée de faire de la sorte.

Balises préférées

Les balises populaires comme <b> et <i> sont considérées comme dépréciées. Du fait de leur popularité, les navigateurs les supporteront certainement encore pendant un certain temps. Néanmoins, il y a de meilleures alternatives. Pour <b>, la balise de remplacement est <strong>. Pour <i>, la balise de remplacement est <em>. Si possible, utilisez ces balises de remplacement aussi bien pour les sorties générées par Coppermine que pour la documentation.

Crédits pour les règles de codage

Les règles principales de cette page ont été esquissées par Dr. Tarique Sani comme un sous-ensemble de lignes directrices de codage PEAR. Les sorties HTML et la section concernant la base de donnée sont basées sur un sujet crée par Unknown W. Brackets Simplemachines.

Facilité d'utilisation

Formulaires

Moins il y a de clics, mieux c'est

Une plus grande surface cible pour les clics