Coppermine Photo Gallery v1.5.x: Documentation and Manual

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.

Objet

Comme Coppermine est un tavail d'aquipe, 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 réspecter lorsque l'on travaille sur le code source de Coppermine. Bien que cette partie de la documentation aux membres de l'éaquipe 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épecter 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, démarez 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é

règles générales

• Dans les requêtes ou dans le code, mettez toujours un espace avante 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 si ils ne contiennent qu'une seule valeu
• 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'), // Since it is just one value in array, it can be declared in same line
            'third'  => array(
                         'foo'   => 'bar',
                         'hello' => 'world',
                        )
           );
          

Structures de Controle

cela inclue if, for, while, switch.

• Les éléments de Controle doivent avoi un espace entre le mot clé de controle 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'; 
  }

Appels de 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 chaques 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 focntions qui ont été enlevées par la suite!) a 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 de HTML à afficher, la syntaxe Heredoc doit être utilisée au lieu de suspendre le processus PHP pour le rependre ensuite.

Bon:

// Contenu Php ici
if ($foo == $bar) {
	print <<< EOT
	<h1>Hello {$bla}</h1>
EOT;
}

Mauvais:

// Contenu Php ici
if ($foo == $bar) {
	?>
	<h1>Hello <?php echo $bla; ?></h1>
<?php
}

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 désinfectées en utilisant Inspekt - référez vous au chapitre "Désinfection 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 miniscules
• Comme toujours, les noms déscriptifs (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ée

• 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é de MySQL
• N'utilisez pas de fonctions Mysql qui ne sont pas utilisables avec MySQL 3.23.4 et précédent
• Optimisez toutes le requêtes pour MySQL 4, même si comme dit plus haut elles doivent fonctionner avec une version antérieure
• Gardez tous les id uniques, et essayez de garder le même id et nom lorsque les deux sont spécifés
• 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 un 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 exeption à cette règle de validité aux standarts: si le code respectueux des standarts brise les fonctionnalités de base des navigateurs proncipaux comme l'actuelle implémentation des ojects embarqués qui ne sont pas respectueux des standards parceque IE5.x " misbehaving" in standards-compliant mode, it is acceptable to create output that doesn't validate. If this is the case, make sure to at least make others aware of this (known issues section of the docs is the best place, but at least add some comment to the code).

Balises Images dans les sorties HTML

• Toujours mettre un attribut alt à tous les éléments images, même si le "alt" est vide
• N'utilisez pas le titre comme contenu du "alt", ne l'utilisez que si le titre est necessaire (comme pour les icones)

Liens dans les sorties HTML

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

Deprecated tags

Deprecated HTML tags like <font> mustn't be introduced into Coppermine unless there is a valid, documented reason to do so.

Prefered tags

The popular tags <b> and <i> are considered to be deprecated tags as well. Because of their popularity, browsers will probably support them for a long time. However, there are better alternatives. For <b>, the replacement tag is <strong>. For <i>, the replacement tag is <em>. If possible, the replacement tags should be used both in HTML output generated by Coppermine as well as the documentation.

Credits pour le guide 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 de Simplemachines.