meta data for this page
  •  

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
develop:codingstyle [2012/12/13 18:24] – [Language and translation] michieldevelop:codingstyle [2016/11/16 14:29] (current) – Removed rules already covered by PSR1&2; Removed reference to API docs; Removed requirement for stating function author; Made @param and @return mandatory samtuke
Line 1: Line 1:
 +====== Coding Style ======
  
 +phpList follows the coding standards of PHP-FIG [[http://www.php-fig.org/psr/psr-1/|PSR-1]] and most of [[http://www.php-fig.org/psr/psr-2/|PSR-2]]. Please follow the simple style rules outlined by these standards to keep code consistent and readable.
 +
 +All changes to the phpList 3 and phpList 4 codebases must adhere to the coding standards. You are only responsible for the lines that you edit.
 +
 +phpList 3 does not uniformly follow the above standards as it is an older codebase not fully renewed. phpList 4 already adheres to these standards.
 +
 +===== SQL Queries =====
 +
 +Build the query using ''sprintf'' for the parameters and store it in a variable before actually calling the query. ((That makes it easier to debug by printing the query before it's performed)) The integer parameters can be sanitised with %d and strings by calling Sql_Escape, eg
 +
 +<code>
 +$query = sprintf('select id,data from %s where id = %d and name = "%s"',$GLOBALS['tables'][$table],$ID,Sql_Escape($NAME));
 +$result = Sql_Query($query);
 +</code>
 +
 +Explicitly mention the columns in the result set and do not use wildcards. So, that means queries like
 +
 +<code>Select u.id, u.status from table u where id = X</code> and **NOT**
 +
 +<code>Select * from table u where id = X</code> ((This is for security purposes.))
 +
 +Also, have a look in the mysql.inc file for the functions that abstract the Mysql calls. Use the ones in there, and do not use any ''"mysql_" functions'' in the code directly.
 +
 +You can use ''Sql_Verbose_Query'' to have the query be printed before being called.
 +
 +All tables are referenced using the global ''$tables''. Check the ''structure.php'' file to find the database structure.
 +
 +====== Language and translation ======
 +
 +When you output strings, use the function ''s''. A lot of code will use ''$GLOBALS['I18N']->get('', but you can use the shortcut ''s'' instead, eg
 +
 +<code>
 +print s('Please enter your name');
 +</code>
 +
 +The ''s function'' can also handle additional parameters which can be used for fill out a sprintf output.
 +
 +<code>
 +print s('phpList has sent %d out of %d messages, and will finish sending at %s',$messages_done,$total,$end_date);
 +</code>
 +((I actually need to check that this is processed correctly by POedit))
 +
 +===== Obsolete coding style =====
 +
 +A lot of code still has these styles, but should be redone. Try to change it whenever you touch a certain section of the code where this is used. But be careful to ensure it doesn't break anything.
 +
 +  * if ($variable)
 +This should be changed to '' if (!empty($variable))) '' or '' if (isset($variable)) '' depending on the context. In general the first one.
 +
 +  * Queries that look like ''"select something from {$tables['table']} where id = $id"''
 +These should be redone using the sprintf format as mentioned above.
 +
 +
 +
 +
 +===== Commenting =====
 +
 +Each function and class should have a PHPDocumentor style comment, giving at least the function's purpose, parameters, and return variable type.
 +
 +Example:
 +
 +<code php>
 +/**
 + * Check for foo in bar
 + *
 + * Checks if there is a foo in bar
 + *
 + * @author   Joe Schmoe <joe@example.com>
 + * @param    string $in your input
 + * @return   bool       true if foo in bar
 + *
 + */
 +function is_foo($in) {
 +  ...
 +}
 +</code>