Revision [1890]

This is an old revision of ContributingtowebERP made by PhilDaintree on 2010-09-10 18:33:44.

 

webERP logoHomePage What Is webERP WeberpFeatures webERP Features WeberpFaq FAQsWeberpSupport Support Sourceforge Project Page Download
|Demo Manual WeberpDevelopment Development


Contributing to webERP


GOALS of webERP


1. To provide fast, web-based, integrated "best practise" business administration software.

2. To be "low footprint" efficient and fast, with absolutely minimal network traffic.

This is to enable dial up/low band-width connections to work with reasonable response times. This will require some compromises with the use of graphics.

3. Platform independence.

Originally the use of Javascript was avoided due to the inconsistencies between implimentations. However, subject to certain rules javascript can be used.
1. Any use of javascript must have another server based option as a fallback - so client machines without javascript enabled will still function.
2. No significant blocks of javascript to choke dialup connections (see goal 2).
3. The javascript used should be used consistently throughout the code.

4. Scripts easily readable and modifiable by a business.

PHP code written using control structures in a consistent way throughout. (See style guide)
Well spaced and rigorously indented.
Extensive commenting.
Long descriptive variable names.
There is also an interesting compromise between good programming practice in maximising code reuse through the use of includes, classes and common functions and in the number of separate scripts required to be understood before a developer has enough confidence to consider modifying the script. I believe that too many levels of abstraction can detract from ease of understanding the script. For this reason includes are used in preference to function calls where possible. Abstracting PHP functions to separate user-defined PHP functions is avoided. Use of OOP is restricted to those areas where large amounts of re-use are possible.

webERP uses a few common include files throughout that must be understood:

includes/ConnectDB.inc - database abstraction
includes/session.inc - initiation of session and security checking
includes/header.inc - page headings and quick menu links
includes/footer.inc - page footer
includes/DateFunctions.inc - Date functions (included in session.inc)
includes/MiscFunctions.inc - Functions for printing messages prnMsg
includes/PDFStarter.inc - PDF report generation
includes/SQL_CommonFunctions.inc - common functions that retrieve database info or update the database eg GetNextTransNo

and config.php which is included by includes/session.inc and is separate from session.inc only because it requires user editing to enter the database user and password.

Most scripts use all the first 6.
Transactional scripts also use an includes/DefineXXXXXXClass.php script.
PDF reporting scripts generally have an includes/PDFXXXXXXXPageHeader.inc script for the report page titles.

Apart from these files above, most scripts are otherwise self contained so that a knowledge of these includes and the main script should be all thats needed to be confident in modifying the script.

CONTRIBUTIONS


Contributions to the webERP project are encouraged - these simple procedures for doing so are aimed at reducing the confusion and co-ordinating the efforts of all contributors:

1.Join the developers mailing list.

http://lists.sourceforge.net/lists/listinfo/web-erp-developers

Inform the list of your proposed developments and discuss the approach to be used. There are some knowledgeable people on the list and they can contribute ideas if you let them. This is also good to avoid overlapping effort or combine efforts in working on different elements of the same project.
A few points to remember about the mailing list:

2. Obtain the latest development scripts from SVN - see sourceforge instructions for anonymous SVN checkout the SVN files initially then updates daily - this only downloads any modified scripts, or update immediately before commencing any development.


IMPORTANT: Only do development work on the most recent scripts from SVN and update your copy of the SVN regularly. Instructions on the use of SVN at sourceforge can be found at the following URL:

http://sourceforge.net/projects/web-erp/develop

3. This point is relevant only for developers that do not have SVN write access. After any modifications to the scripts - email (only) the modified scripts (and ideally a diff file between the latest SVN scripts and your updated scripts) to submissions@weberp.org within 12 hours of your last update from SVN. The project admin will have to digest the modifications and ensure the coding style is consistent, test the scripts and consider the implications of the modifications in achieving the goals noted above. Plenty of narrative explaining the modifications should be posted in the developers list so all can consider the implications. They will be committed to SVN as soon as possible after receipt and testing.

4. Where modifications span 10 or more scripts at the same time, request a stay on development from other developers using the list.

5. All submissions of modifications or additions should be accompanied by a plain text change.log file describing the changes to each script. This explains to everyone the nature of the changes made. Each entry in the change log should state the developer name and date of the change/addition. This file will be appended to the doc/change.log when the files are committed to SVN.

6. Requests for modification of the database structure - with an extract of the SQL required to effect the changes should be made to submissions@weberp.org These will be included in the version upgrage script as well as the latest database structure.

CODING STANDARDS


Function/Class/Variable 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 variable $i can be used as a counter.

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. This has changed since all code was written with (x)html in capitals. The code has many places currently where the html is in upper case - this will be changed over time to lower case.

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 or punctuation 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['StartAtCustomer'] 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.

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.

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']



Control Structures

All control structures (these include if, for, while, switch) must always use "Kernighan and Richie" 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.

Function defintions should follow the same conventions.

It is recommended that you break lines at approximately 75-85 characters.


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 revision number in it if the following comment is pasted into it the CVS automatically updates the revision number.
/* $Revision: 1.7 $ */


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.

Table and field names should alway use lower case.

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.

Constants

Constants should always be all-uppercase, with underscores to separate words.


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