Download - Bb Tequila Coding Style (Draft)
Tequila Coding StyleVersion 1.0 (Draft)
Siwawong W.Siwawong W. 30 October, 2009
Copyright ® 2009 by Blue Ball Co., Ltd. All rights Reserved
Coding Practices
General OOP
General Development
Application Security
Copyright ® 2009 by Blue Ball Co., Ltd. All rights Reserved
Coding Practices(1) General OOP
• Make use of classes to encapsulate functionality.– Doesn’t allow to use Global Variables (including in session too) except on config.php and Global PHP
variables.
• Make use of exceptions for error conditions.
• Ensure exception hierarchy is clearly defined, and do subclass exceptions when specializing is necessary to differentiate different error conditions.
• Make use of interfaces to define contracts between components where necessary.
• Ensure attribute/member visibility is as restrictive as possible. i.e. keep as private all the time, change to protected/public only when needed to.
– Default property is PROTECTED.
• Avoid “deep” inheritance hierarchy. Keep them to 1-3 levels, but subclass exception classes as necessary.
– In framework is use deep inheritance enough
Copyright ® 2009 by Blue Ball Co., Ltd. All rights Reserved
Coding Practices
General OOP
General Development
Application Security
Copyright ® 2009 by Blue Ball Co., Ltd. All rights Reserved
Coding Practices(2) General Development
• Make use of SVN for version control.– Synchronized code in our local server in office only.
• Always commit daily, at the end of day, only after all testing has been performed to ensure your code works.
– This procedure is done in local server only.
• Retrieve updates before committing them to ensure your code still works with the latest codes in SVN.
• Delivery update code to BKK, required to use Mercurial (aka, Hg) for fast update
• If BKK has something changes, we will delivery to VN via Hg also.
Note: - Hg procedure for check-in/out, BKK team will provide later.
Copyright ® 2009 by Blue Ball Co., Ltd. All rights Reserved
Coding Practices
General OOP
General Development
Application Security
Copyright ® 2009 by Blue Ball Co., Ltd. All rights Reserved
Coding Practices(3) Application Security
• Contents Management System (aka, CMS)– Latest versions of the CMS will be installed.
– Subscribe to newsletters and important announcements in the CMS groups to ensure latest versions are always installed.
Note: - in general website function, we have feature to get feeds from CMS. Upon to site to get feeds.
• Database– Avoid use of “root” / “admin” / “sa” database user logins.– Enforce necessary permissions for database and database tables.
Copyright ® 2009 by Blue Ball Co., Ltd. All rights Reserved
Coding Practices(3) Application Security (Cont’)
• Application
– Validate all inputs on server side with AJAX.
– Ensure parameters are encoded to avoid cross site scripting.
– Prevent URLs from being passed as a parameter to scripts.
– Enforce user password change policy.
– Log all user activities.(This feature can’t implement now, it’s Tequila’s issue)
– Prevent concurrent access by the same user.
– Any pop-up/error message, not allow to HARD CODING. Please get the message from DB
Copyright ® 2009 by Blue Ball Co., Ltd. All rights Reserved
Tequila Coding Convention
File Organization
Naming Convention
Indentation and Whitespace
Comments
Declarations and Initialization
Programming Practices
More Reference on http://sites.google.com/site/phptequila/
Copyright ® 2009 by Blue Ball Co., Ltd. All rights Reserved
Tequila Coding Convention(1) File Structure
• Based on standard Tequila– Check more detail at http://sites.google.com/site/phptequila/
• Located in APP folder only.– Under APP folder, please split into sub-modules e.g. SO, PO, INV, etc.
• In case, required special library, please keep in Package folder.– e.g. AJAX framework, Web services library, Catcha library, etc.
Copyright ® 2009 by Blue Ball Co., Ltd. All rights Reserved
Tequila Coding Convention
File Organization
Naming Convention
Indentation and Whitespace
Comments
Declarations and Initialization
Programming Practices
More Reference on http://sites.google.com/site/phptequila/
Copyright ® 2009 by Blue Ball Co., Ltd. All rights Reserved
Tequila Coding Convention(2) Naming Convention
• Camel Casing method is used for variables, it capitalizes the first character of each word except the first one
Example:
Variable: protected $isPaymentMade;
• Pascal Casing method is used for class, method, interface, etc, it capitalize the first character for each word in their particulate behaviors.
Copyright ® 2009 by Blue Ball Co., Ltd. All rights Reserved
Tequila Coding Convention(2) Naming Convention (Cont’)
• Example for Class– Class: class Payment {….}
• Use nouns or noun phrases
• Example for Method– Method: void UpdateAccount (….)
• Use verbs or verbs phrases
• Example for Interface– Interface: IComponent or IEnumberable
• Use nouns or noun phrases or adjectives describing behavior, Use I as prefix for the name, it is followed by a capital letter (first char of the interface name)
• All Upper cases only for identifiers if it consists of an abbreviation which is one or two characters long
– Example: public class Math { public const PI = …
public const E = … }
Copyright ® 2009 by Blue Ball Co., Ltd. All rights Reserved
Tequila Coding Convention
File Organization
Naming Convention
Indentation and Whitespace
Comments
Declarations and Initialization
Programming Practices
More Reference on http://sites.google.com/site/phptequila/
Copyright ® 2009 by Blue Ball Co., Ltd. All rights Reserved
Tequila Coding Convention(3) Indentation and Whitespace
• Recommend the “Tab” for whitepacing, don’t use “Space” for consistency. – A “Tab” represent 1 character, two “Space” will represent 2 characters, four “Sp
ace” will represent 4 characters, hence “Tab” also reduces the typing
• Break the wrapping lines based on the following principles– Break after comma
Example: void PaymentHistory ($paymentDate,
$paymentDescription, $paymentAmount) – Break after operator var = a * b / (c - g + f) + 4 * Z; – Align the new line with the beginning of the expression at the same level on thepr
evious line. Use “Tab” if possible as previous examples above
Copyright ® 2009 by Blue Ball Co., Ltd. All rights Reserved
Tequila Coding Convention(3) Indentation and Whitespace (Cont’)
• Use the single space after the comma, semicolon, surround operators. No spaces between a method name and the parenthesis
• Use the open brace and close brace for a class in systematic way; stick it to one style and using it along the whole project files.public class Payment{…}
• Use open brace and close brace for control statements– Example: If, If…Else…, while, etc.
Copyright ® 2009 by Blue Ball Co., Ltd. All rights Reserved
Tequila Coding Convention
File Organization
Naming Convention
Indentation and Whitespace
Comments
Declarations and Initialization
Programming Practices
More Reference on http://sites.google.com/site/phptequila/
Copyright ® 2009 by Blue Ball Co., Ltd. All rights Reserved
Tequila Coding Convention(4) Comments
• Use ///your comment– for the comments and single line comments and it mu
st be indented properly to the indent level.
• Use /*your comments*/– Only for very large section of codes, avoid using it for
small block codes also as this will set off the block visually from code for the (human) reader
Copyright ® 2009 by Blue Ball Co., Ltd. All rights Reserved
Tequila Coding Convention
File Organization
Naming Convention
Indentation and Whitespace
Comments
Declarations and Initialization
Programming Practices
More Reference on http://sites.google.com/site/phptequila/
Copyright ® 2009 by Blue Ball Co., Ltd. All rights Reserved
Tequila Coding Convention(5) Declarations and Initialization
• Try to initialize a variable once it is declared. One declaration per line is recommended
Example: $payment = 0;
$description = “”;$isPaymentmade = false;
• Try…catch… statement is required for every initialize statements.
Copyright ® 2009 by Blue Ball Co., Ltd. All rights Reserved
Tequila Coding Convention
File Organization
Naming Convention
Indentation and Whitespace
Comments
Declarations and Initialization
Programming Practices
More Reference on http://sites.google.com/site/phptequila/
Copyright ® 2009 by Blue Ball Co., Ltd. All rights Reserved
Tequila Coding Convention(6) Programming Practices
• Do not make any instance or class variable public, make them private or just do write nothing. Private is the default case.
• Don’t use magic numbers, i.e. place constant numerical values directly into the source code. Place them in configuration table.
• Store the constant, enum etc regarding the database columns value into the Data Access Layer.
• Place each module in its own directory.
• Use the proper and understandable naming convention for all the variables.