Coppermine Photo Gallery - Your Online Photo Gallery

Coppermine Photo Gallery v1.5.20: Documentation et manuel


Table des matières
Passez votre souris ici pour dérouler

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

Encodage

L'encodage standart dans Coppermine est UTF-8 sans BOM. Tous les fichiers non-binaires doivent être encodés en UTF-8 (Unicode).

Règles générales

Code PHP

Formatage

Structures de contrôle

cela inclue if, for, while, switch.

Appel des fonctions

Définition des fonctions

Balise de code PHP

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.

Bon:

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

Mauvais:

// 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.

Bon:

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

Mauvais:

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

Convention de nommage

Pour les créateurs de plugins il y a une section plus détaillée sur les conventions de nommage décrivants aussi les noms de packages.

Requêtes dans la base de données

Documentation

Sortie HTML

Balises images dans les sorties HTML

Liens dans les sorties HTML

Eléments de formulaires dans les sorties HTML

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

Avoir de bonnes connaissances en programmation est important, mais il est tout aussi important de coder correctement en terme de facilité d'utilisation.

Formulaires

Moins il y a de clics, mieux c'est

Les listes déroulantes sont géniales s'il y a beaucoup d'options de choix, mais elles sont moins bonnes si il n'y a que deux ou trois options: l'utilisateur doit cliquer sur la liste pour voir quelles options existent.
Au lieu de venir avec un liste de sélection comme
il est plus intuitif pour l'utilisateur d'afficher les différentes options possibles sous forme de boutons radio:
Si vous voulez juste un commutateur pour basculer d'une option à l'autre utilisez une boite à cocher comme
au lieu de
Afficher le graphique:
ou même

Une plus grande surface cible pour les clics

Il peut être difficile de cliquer sur une simple case à cocher ou un bouton radio - c'est la raison pour laquelle la balise HTML <label> a été inventée: si vous l'utilisez judicieusement, le texte correspondant à une option particulière représentée par une case à cocher ou un bouton radio peut être cliquable pour changer l'état de la case à cocher ou du bouton radio.
Mauvais exemple Bon exemple
Sortiet Aller au premier
Restez ou vous êtes
Aller au dernier
Code
<input type="radio" name="option_nolabel" value="0" class="radio" checked="checked" />Aller au premier<br />
<input type="radio" name="option_nolabel" value="1" class="radio" />Restez ou vous êtes<br />
<input type="radio" name="option_nolabel" value="2" class="radio" />Allez au dernier
Sortie

Code
<input type="radio" name="option_label" id="option_label0" value="0" class="radio" checked="checked" />
<label for="option_label0" class="clickable_option">Aller au premier</label><br />
<input type="radio" name="option_label" id="option_label1" value="1" class="radio" />
<label for="option_label1" class="clickable_option">Restez ou vous êtes</label><br />
<input type="radio" name="option_label" id="option_label2" value="2" class="radio" />
<label for="option_label2" class="clickable_option">Allez au dernier</label>
Sortie Display graph
Code
<input type="checkbox" name="display_graph_nolabel" value="1" class="checkbox" />Display graph
Sortie
Code
<input type="checkbox" name="display_graph_label" id="display_graph_label" value="1" class="checkbox" /><label for="display_graph_label" class="clickable_option">Afficher le graphique</label>
Cliquez sur les mots à côté des boutons radio pour voir la différence !