User Tools

Site Tools


develop:codingstyle

Differences

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

Link to this comparison view

Both sides previous revision Previous revision
develop:codingstyle [2013/04/25 22:36]
phplist
develop:codingstyle [2016/11/16 14:29] (current)
samtuke Removed rules already covered by PSR1&2; Removed reference to API docs; Removed requirement for stating function author; Made @param and @return mandatory
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>​
develop/codingstyle.txt · Last modified: 2016/11/16 14:29 by samtuke

Resources
Contact Us

e: info@phplist.com

Boring Bit

phpList is a registered limited company

UK Company No. 07582966

VAT Registration 122 0788 37

© phpList 2016