Re: [Web-erp-developers] Contribution Guidelines - 2nd Draft

[skaill <sk...@ro...>]

In goals,

4. By use of plain English do you mean comments, message strings, ....?

In contributions,

5. I was wondering where the change.log was but found it in webERP > doc...

Steve 

----- Original Message ----- 
From: "Phil Daintree" <p.d...@pa...>
To: <web...@li...>
Sent: Friday, August 06, 2004 10:28 PM
Subject: [Web-erp-developers] Contribution Guidelines - 2nd Draft


> 
> I have drafted up another shot at contribution guidelines - once
> everyone is happy with it I will put it up as a document on sourceforge.
> 
> As always - comments appreciated.
> 
> Phil
> 
> 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.
> 
> I have steered deliberately away from Java due to the inconsistencies
> between implimentations.
> Java also increases the bandwidth requirements with downloading the
> software - although I recognise there can also be a saving in "round
> trips" to the server. However, Java is not available on some PDA
> browsers and it takes memory and processing power at the client. Aim
> number 1 requires us to keep the software requirements at the browser
> end as minimal as  possible - just a pdf reader and any browser.
> 
> 4. Scripts easily readable and modifiable by a business.
> 
> You will notice extensive use of plain english throughout.
> 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
> practise 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 condidence to consider
> modifying the script. I believe that too many levels of abstraction can
> detract from ease of understanding the script. webERP uses a few common
> include files 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/PDFStarter_ros.inc - PDF report generation substitute for
> session.inc
> includes/DateFunctions.inc - Date functions
> 
> and config.php which is included by includes/session.inc. Most scripts
> use all the first 4. Transactional scripts also use an
> includes/DefineXXXXXXClass.php script. Apart from these files most
> scripts are otherwise self contained so that a knowledge of these
> includes and the 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 knowlegable 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.
> 
> 2. Obtain the latest development scripts from CVS - see sourceforge
> instructions for anonymous cvs checkout the CVS files intially then
> updates daily - this only downloads any modified scripts, or update
> immediately before commencing any development.
> 
> http://sourceforge.net/docman/display_doc.php?docid=14033&group_id=1
> 
> 3. After any modifications to the scripts - email (only) the modified
> scripts (or ideally a diff file between the latest CVS scripts and your
> updated scripts) to dai...@so... within 12 hours of your
> last update from CVS. 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 acheiving
> 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 CVS as soon as possible after
> receipt and testing. Only the project admin has write access to CVS.
> 
> 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 CVS.
> 
> 6. Requests for modification of the database structure - with an extract
> of the SQL required to effect the changes should be made to
> dai...@so... 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;
> 
> 
> 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.
> 
> 
> Control Structures
> 
> All control structures (these include if, for, while, switch) must
> always use 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!
> 
> 
> Database Function Calls
> 
> There should never be any database specific calls in scripts other than
> includes/ConnectDB.inc
> All database calls should be performed by calling the abstraction
> functions in that script.
> 
> 
> SQL
> 
> Should be as ANSI compliant as possible.
> 
> 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 ";
> 
> 
> 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.
> 
> 
> 
> -------------------------------------------------------
> This SF.Net email is sponsored by OSTG. Have you noticed the changes on
> Linux.com, ITManagersJournal and NewsForge in the past few weeks? Now,
> one more big change to announce. We are now OSTG- Open Source Technology
> Group. Come see the changes on the new OSTG site. www.ostg.com
> _______________________________________________
> Web-erp-developers mailing list
> Web...@li...
> https://lists.sourceforge.net/lists/listinfo/web-erp-developers