====== Coding standards =======

Whether you are developping a plugin, or want to correct a bug, or simply add a functionality, following these few rules is necessary.

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

==== PHP Configuration =====

All of Dotclear's code must function with the following PHP configuration:

  * 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

Code should work with PHP 5.0 at a minimum.

<note tip>
In order to change the value of error_reporting to ''E_ALL | E_STRICT'', you need to uncomment the beginning of the file ''/dotclear/inc/prepend.php'' by adding a slash (''/'') before ''/*== DC_DEBUG =='' or add the following code at the end of the file ''/dotclear/inc/config.php'' in order not to halt the automatic update feature.

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

</note>

==== Indentation, line length ====

Use an indentation in real tabulations (not in spaces). The usual (and practical) width of a tabulation is of 5 spaces in Dotclear's code.

Lines should not exceed 70 characters in length.


==== Control structures ====

The control structures are the if, switch, for, while, foreach, etc. instructions. You must leave a space between the instruction's keyword and the condition. The bracket's position is up to you.

=== Example of control structures: ===

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

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

==== Calling functions ====

The functions are called without any space between the name of the funtion, the parenthesis and the parameters. For example:
Les fonctions sont appelées sans aucun espace entre le nom de la fonction, les parenthèses 

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

If the function is returned in a variable, at least one space should be used on either side of the equal sign. For example:

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

==== Functions definitions ====

The function's brackets are placed under its name and the code is indented (one level). For example:

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


==== Commentaires ====

Comments on a line are often made with the # sign, less with the %%//%%.
Comments for several lines are made with the /* comment */ style.

Deactivating a portion of the code with a comment will be done with /* %%//%%*/. In this manner it takes only a / to deactivate the comment. For example:

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

<note tip>
You can use the Doxygen conventions to comment the code the Dotclear way:
  * [[http://www.stack.nl/~dimitri/doxygen/docblocks.html|General Doxygen documentation]]
  * [[http://www.stack.nl/~dimitri/doxygen/commands.html|Special Doxygen commands]]
</note>

==== File inclusion ====

A file is included in another relatively to the first one. This is mandatory. For example:

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

==== Tags in the HTML code ====

PHP code is always delimited with <?php ?> and not with the abbreviated version <? ?>. This is mandatory. The form <?= ?> is of course proscribed.


==== Naming conventions ====

=== Classes ===

Classes are always names with unaccentuated characters. Words are separated with uppercase letters and the name of the class starts with a lowercase. For example:

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

=== Functions ===

Functions' names follow the same rules as those of classes.

=== Variables ===

The name of the variables must have a meaning. The words are separated by underscores (_). For example:

<code php><?php
$my_variable = 'text';
$var = 'text...';
?></code>

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

Dotclear tries to comply as much as possible to HTTP, which implies a certain number of rules.

==== Modifying data ====

All data change (in the database or elsewhere) **must** happen through a HTTP POST request.

More over, all requests of this type must send a field names "xd_nonce" containing an identifier allowing to check its legitimity.

It is therefore necessary to send this field to all forms of the type POST. For example:

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

Calling the $core->formNonce() method automatically inserts a hidden field containing the value of //nonce// in the form.

Finally, what is valid for form submissions is also valid for requests made via //XML HTTP Request// (Ajax) of the POST type. Dotclear provides a javascript variable containing the //nonce//: dotclear.nonce.


Example of an ajax request with nonce:

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

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

<note>
//nonce// is checked automatically and its use is only required for the administration part of Dotclear, not for the public part.
</note>

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

Make sure the XHTML code of your theme or plugin is valid. It is possible to check the validity of the XHTML even if it is not accessible (for example in the administration) thanks to the [[https://addons.mozilla.org/fr/firefox/addon/60|Web Developer]] extension for Mozilla Firefox.

===== Database =====

In order for a plugin or a theme which accesses the database to function properly on all blogs, it must be tested with MySQL and PostgreSQL (PGSQL). If you can't make the tests with one of those database types, ask for help on the [[http://forum.dotclear.net/|Dotclear forum ]].