Revision [2444]

This is an old revision of CodingConventions made by PhilDaintree on 2012-02-17 02:18:38.

 

webERP logoHomePage What Is webERP WeberpFeatures webERP Features WeberpFaq Documentation

WeberpSupport Support Forum Sourceforge Logo Download Demo WeberpDevelopment Development


Contributing to webERP


CODING STANDARDS


It is a core goal of webERP to be easy to read for business people and newcomers to PHP. This requires some compromises, but mostly much of these standards represent good programming practise and the adoption of conventions which make the code consistently easy to read throughout.

All code in webERP must conform to these standards.


Function/Class/Variable/Field Naming

Descriptive names should be used in preference to short variable names:

eg.
$a = 3.14159;

should be avoided in favour of:
$Pi = 3.14159;

The variables $i $j and $k can be used as a counters.

As displayed above, there should be one space on either side of an equals sign used to assign the return value of a function to a variable. In the case of a block of related assignments, more space may be inserted to promote readability:
$Short         = foo($bar);
$LongVariable = foo($baz);


Good descriptive variable names consisting of several words appended togther should have the first letter of each word capitalised.

eg.
$longvariablename = 1;


should be written as:
$LongVariableName = 1;


HTML

HTML keywords and tags should be in lower case to improve xhtml compatibility.

HTML table cell tags in echo statements should use carriage returns to keep cells together so it is easy to see what is in each cell.

eg.
echo '<table><tr><td>' . _('Label text') . ':</td><td>' . $SomeVariable . '</td><td>' . _('Some Other Label') . '</td><td align=right>'  . number_format($SomeNumber,2) . '</td></tr></table>';

Would be more easily digested and should be written as:
echo '<table>
	<tr>
		<td>' . _('Label text') . ':</td>
		<td>' . $SomeVariable . '</td>
		<td>' . _('Some Other Label') . ':</td>
		<td align=right>' . number_format($SomeNumber,2) . '</td>
	</tr>
	  </table>';

Carriage returns should be used in a similar way for printf statements.

All values of xhtml properties should be between double quotes e.g. <input type="text" name="InputBox" value="Default">
This goes hand in hand with using single quotes for all echo statments see below.

Label Strings and Multi-Language

Since webERP is a multi-language system it is important not to compromise this capability by having labels in your scripts that are not enclosed in the gettext function eg.
echo 'Enter the quantity:<input type="text" name="Quantity">';

should be written as:
echo _('Enter the quantity') . ':<input type="text" name="Quantity">';

note that there should be no trailing spaces on the string to be translated inside the _() function call

PHP Variables

The PHP variable arrays $_POST, $_GET, $_SERVER, $_SESSION provide context about where a variable comes from - many developers are tempted to abbreviate:
$StartingCustomer = $_POST['StartingCustomer'];

or worse:
$s = $_POST['StartingCustomer'];

This should be avoided in favour of using $_POST['StartingCustomer'] everywhere it is required so the reader can see where the variable comes from.

However, variables which could come from either a $_GET or a $_POST and/or a $_SESSION may be assigned as in the first example since there is no value in the context.

PHP Functions and Keywords

Always in lower case

With the Exception of PHP Logical Operators

i.e. AND and OR

Always in UPPER CASE - the upper case separates the predominantely lower case comparison expressions for improved readability.

e.g.
if ($OneTwoThree==$_POST['OneTwoThree'] and $myrow['onetwothree']==$_SESSION['OneTwoThree']) {


should be written as:
if ($OneTwoThree==$_POST['OneTwoThree'] AND $myrow['onetwothree']==$_SESSION['OneTwoThree']) {


Where there are many comaparisons new lines should be created for each comparison

if ($OneTwoThree==$_POST['OneTwoThree'] 
	AND $myrow['onetwothree']==$_SESSION['OneTwoThree']) {


Quotation Marks

Notice that single quotes (') are used in preference to double quotes (") - there is additional overhead for php in parsing data within double quotes. They should only be used where absolutely necessary and concatenation of variables is preferred to having variables inside double quotes.

eg.
echo "Some text with a $Variable";

would be better written as:
echo _('Some text with a') . ' ' . $Variable;

to reduce the parsing job required of the web-server. Notice all strings need to be inside the gettext _() function.

Arrays and super global arrays should always have the element name within single quotes not doubles

eg.
$_POST["FormVariableName"]

should be written as:
$_POST['FormVariableName']


The only exception to this is that when constructing SQL statements, due to the requirement to single quote string literals in SQL statements, the entire SQL string should always be written using double quotes. (See below)


Control Structures

All control structures (these include if, for, while, switch) must always use "1 True Brace" style statement blocks.
You are strongly encouraged to always use curly braces even in situations where they are technically optional. Having them increases readability and decreases the likelihood of logic errors being introduced when new lines are added.

eg.
if ($VariableName == true) echo _('Variable was true');


whilst legal PHP syntax, this should be avoided in favour of the following syntax:

if ($VariableName == true) {

	echo _('Variable was true');
}


Parenthesis should open on the same line (after a space) as the initiating control structure and close the statement block at the same level of indenting as the initiating line.

Else statements should be on the same line as the closing statment block from the preceeding elseif or if statement eg.
if ($VariableName == true) {

	echo "Variable was true";

} else {

	echo "Variable was false";

} /*end else $VariableName was false*/

This is the only time there should be anything other than a comment on the closing curly brace line. Comments on a closing curly brace line where the block has been quite a few lines of code are encouraged to show the control structure to which they related.

Whenever a statement block is used code within the block should be one tab indented. Indenting code correctly is critical to avoid logic errors and to imrpove readability.

Function defintions should follow the same conventions.

Most programming editors have word wrap and this is preferred to manual line breaks.

Spacing

Where readability is improved lines of code should be separated by a line


Comments

C style comment blocks in the format:
/* comments in here */

are preferred. But all comments gratefully received!

All scripts should have a comment in the first few lines with the script name and revision number in it if the following comment is pasted into it the SVN repository automatically updates the revision number.
/* $Id: AccountGroups.php 4735 2011-10-29 05:59:53Z daintree $*/


Messages

The standard message function prnMsg should always be used for all messages to be echo'ed to the screen - this function has two parameters - the string to display and the message type , 'error', 'warn', 'success', 'info' - there is a third optional paramter which is a prefix heading for the message.

Database Function Calls

There should never be any database specific calls in scripts other than includes/ConnectDB_XXXX.inc
Where XXXX is the abbreviation for the RDBMS the abstraction code refers to.
All database calls should be performed by calling the abstraction functions in those scripts. (currently only includes/ConnectDB_mysql.inc exists - 2007 - ConnectDB_postgres.inc was depreciated but could easily be revived if we stick with this convention)


SQL

Should be as ANSI compliant as possible. Using SQL which is particular to a specific RDBMS is to be avoided in favour of the ANSI equivalent.

The webERP goal of providing "low footprint" efficient system - requires careful thought. The number of "round trips" must be minimised - never go off to the database to get data that could have been got in a prior query. This is inefficient design and to be avoided.

Table and field names should alway use lower case and should be descriptive of the data they hold. e.g. Field names such as "nw" should be avoided in favour of "netweight"
There is a temptation for some developers to try to reuse tables for other purposes by adding a field or two. If the data is not common accross all rows then it probably belongs in a separate table. There is no overhead to having separate tables, but there is a whole table full of waste fields where only a few records need the field.

SQL statements should be on several lines for easier reading eg.
$sql = "select transno, trandate, debtortrans.debtorno, branchcode, reference, invtext, order_, rate, ovamount+ovgst+ovfreight+ovdiscount as totalamt, currcode from debtortrans inner join debtorsmaster on debtortrans.debtorno=debtorsmaster.debtorno where ";


is harder to read than:
$sql = "SELECT transno,
		trandate,
		debtortrans.debtorno,
		branchcode, reference,
		invtext,
		order_,
		rate,
		ovamount+ovgst+ovfreight+ovdiscount AS totalamt,
		currcode
	FROM
		debtortrans INNER JOIN debtorsmaster
		ON debtortrans.debtorno=debtorsmaster.debtorno
	WHERE ";


SQL kywords should be capitalised as above eg. SELECT, CASE, FROM, WHERE, GROUP BY, ORDER BY AS INNER JOIN etc.
Line breaks after every comma and on major SQL reserved words as above.

SQL queries should always "escape" strings using the function "DB_escape_string", integer values with "intval" function and floating point numbers with "floatval" function, that is to prevent SQL injection attacks.

Quoting SQL variables - variables incorporated into SQL strings need to be inside SINGLE quotes so that the variable cannot be used by a hacker to send spurious SQL to retrieve private data.

NOTE: Since variables incorporated into an SQL string need to be quoted with single quotes inside the SQL string, the SQL strings themselves need to be quoted inside double quotes.

This is the one exception to the general rule to always use single quotes for strings (which makes the parsing job for PHP easier and quicker).

Constants

Constants should always be all-uppercase, with underscores to separate words. Where it is possible to use a literal instead of a constant then the literal is preferred.


PHP Code Tags

Always use <?php ?> to delimit PHP code, not the <? ?> shorthand. This is the most portable way to include PHP code on differing operating systems and setups.
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki