====== Convention de codage de Dotclear =======

Que vous développiez un plugin, vouliez corriger un bug ou simplement ajouter une fonctionnalité, le suivi de ces quelques règles est nécessaire.

===== Code PHP =====

==== Configuration de PHP =====

Tout le code de Dotclear doit fonctionner avec cette configuration de PHP :

  * short_open_tag = Off
  * allow_call_time_pass_reference = Off
  * error_reporting = E_ALL | E_STRICT
  * display_error = On
  * register_globals = Off
  * magic_quotes_gpc = Off
  * allow_url_fopen = Off

Le code doit fonctionner avec PHP 5.2 minimum.

<note tip>
Pour passer la valeur de error_reporting à ''E_ALL | E_STRICT'', il faut décommenter le début du fichier ''/dotclear/inc/prepend.php'' en ajoutant un slash (''/'') avant ''/*== DC_DEBUG =='' ou ajouter ce code à la fin du fichier ''/dotclear/inc/config.php'' pour ne pas gêner la mise à jour automatique :

<code php>
ini_set('display_errors',true);
error_reporting(E_ALL | E_STRICT);
</code>

</note>

==== Indentation, longueur des lignes ====

Utilisez une indentation en tabulations vraies (pas en espaces). La largeur courante (et pratique) d'une tabulation est de 5 espaces dans le code de Dotclear.

Il est par ailleurs conseillé de ne pas dépasser 70 caractères dans les lignes.

==== Structures de contrôle ====

Les structures de contrôle sont les instructions if, switch, for, while, foreach, etc. Vous devez laisser un espace entre le mot clé de l'instruction et la condition. La position des accolades est à votre discrétion.

=== Exemple de structures de contrôles : ===

<code php><?php
if (condition1 && condition1) {
     action;
}

foreach ($tableau as $k => $v)
{
     action;
     action;
}
?></code>

==== Appels de fonctions ====

Les fonctions sont appelées sans aucun espace entre le nom de la fonction, les parenthèses et les paramètres. Par exemple :

<code php><?php
maFonction($var1,$var2);
?></code>

Si la fonction est retournée dans une variable, on mettra au moins un espace de part et d'autre du signe égal. Par exemple :

<code php><?php
$var = maFonction($var1);
?></code>

==== Définitions des fonctions ====

Les accolades de la fonction sont placées sous le nom de celle-ci et le code est indenté d'un niveau. Par exemple :

<code php><?php
maFonction($var1,$var2=0)
{
     return $var1+$var2;
}
?></code>


==== Commentaires ====

Les commentaires d'une ligne sont fréquemment faits avec le signe #, moins avec les %%//%%. Les commentaires de plusieurs lignes seront faits avec le style /* commentaire */

La désactivation d'une portion de code par un commentaire sera faite avec le code /* %%//%%*/, de cette manière, il suffit d'ajouter un / pour désactiver le commentaire. Par exemple :

<code php><?php
/*
code();
//*/
?></code>

<note tip>
Vous pouvez utiliser les conventions de Doxygen pour commenter votre code à la manière de Dotclear :
  * [[http://www.stack.nl/~dimitri/doxygen/docblocks.html|documentation générale de Doxygen]]
  * [[http://www.stack.nl/~dimitri/doxygen/commands.html|commandes spéciales de Doxygen]]
</note>

==== Inclusions de fichiers ====

Un fichier est inclus dans un autre relativement au premier. Cela est obligatoire. Par exemple :

<code php><?php
require dirname(__FILE__).'/../../fichier.php';
?></code>

==== Tags dans le code HTML ====

Le code PHP est toujours délimité par <?php ?> et non la version abrégée <? ?>. Ceci est obligatoire. La forme <?= ?> est bien entendu proscrite.

==== Conventions de nommage ====

=== Classes ===

Les classes sont toujours nommées avec des lettres non accentuées. Les mots sont séparés par des majuscules et le nom de la classe commence par une minuscule. Par exemple :

<code php><?php
class maClasse
{
//...
}
?></code>

=== Fonctions ===

Les noms de fonctions suivent les même règles que les classes.

=== Variables ===

Les noms des variables doivent avoir un sens. Les mots sont séparés par des _. Par exemple :

<code php><?php
$ma_variable = 'texte';
$var = 'texte...';
?></code>

===== Conventions HTTP =====

Dotclear se conforme au maximum à HTTP ce qui implique de suivre un certain nombre de règles.

==== Modification de données ====

Tout changement d'état (dans la base de données ou ailleurs) doit **obligatoirement** passer par une requête HTTP de type POST.

Par ailleurs, toute requête de ce type doit envoyer un champ nommé "xd_nonce" contenant un identifiant permettant d'assurer la légitimité de celle-ci.

Il est donc nécessaire de passer ce champ à tout formulaire de type POST. Par exemple :

<code php>
<form action="foo.php" method="post">
<p>....</p>
<p><?php echo $core->formNonce(); ?></p>
</form>
</code>

L'appel à la méthode $core->formNonce() insère automatique un champ caché contenant la valeur du //nonce// dans le formulaire.

Enfin, ce qui est valable pour les soumissions de formulaire l'est également pour les requêtes faites via //XML HTTP Request// (Ajax) de type POST. Dotclear fournit une variable javascript contenant le //nonce// : dotclear.nonce.

Exemple de requête ajax avec le nonce :

<code javascript>
params = {
  xd_check: dotclear.nonce,
  p: "param"
};

$.post(url,params,function() {
	...
});
</code>

<note>
La vérification du //nonce// est automatique et son usage n'est requis que pour la partie d'administration de Dotclear, pas pour la partie publique.
</note>

===== Code XHTML =====

Veillez à valider le code XHTML de votre thème ou plugin. Il est possible de valider du XHTML même s'il n'est pas accessible (par exemple dans l'administration) grâce à l'extension [[https://addons.mozilla.org/fr/firefox/addon/60|Web Developer]] pour Mozilla Firefox.

===== Base de données =====

Pour qu'un plugin ou un thème qui accède à la base de données puisse fonctionner sur tous les blogs, il faut qu'il soit testé avec les bases de données MySQL et PostgreSQL (PGSQL). Si vous ne pouvez effectuer de tests avec un de ces types de base de données, demandez de l'aide sur le [[http://forum.dotclear.net/|forum]].