1. Writing Maintainable Code Shaun Moss March 2008 shaunmoss@yahoo.com.au

2. Benefits INCREASED PRODUCTIVITY. Save huge amounts of time and $$$ during implementation and maintenance phases. Coding shortcuts. Ease of maintenance and repairs. Code that's easy to learn and understand. Other developers will be happy to work with the code (outsourcing, delegating). Improved communication between developers. Looks professional. The software will be around for longer.

3. Coding Standards What are they? Code formatting patterns. Syntax patterns. Naming patterns. Benefits: Improved code readability. Improved productivity and maintainability. Reduce errors. Existing standards: PEAR: http://pear.php.net/manual/en/standards.php Java: http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html

4. Coding Standards - Formatting Indenting. Pos of braces: K&R: Same line. Allows more useful lines of code on-screen. function doStuff($x, $y, $z) { $x++; echo $x + $y*$z; } Allman: Next line. Can improve readability. function doStuff($x, $y, $z) { $x++; echo $x + $y*$z; }

5. Coding Standards - Formatting Pos of spaces, commas, semi-colons, etc. General patterns: Function calls: mult($x, $y); Function declarations: function mult($x, $y) Control structures: if ($x == $y) while ($x == $y) for ($i = 0; $i < 100; $i++) Operators: $z = $x + $y; $a = $x - $y*$z; $b = $a++; $s = $catName. is a cat; // $catName is cat

6. Naming Patterns – DB Tables Rule 1: lower_case MySQL database table names. This avoids problems when deploying MySQL databases on different operating systems. e.g. person, basket_item Rule 2: Use singular for table names. Saves typing, easier refactoring. e.g. category not categories Rule 3: Use underscore for linking tables. Linking tables implement many-to-many relationships between two other tables. e.g. person, club, person_club Rule 4: Name primary keys same as foreign keys. e.g. customer.customer_id, not customer.id This is for increased clarity, facilitates object-oriented database programming (where records from multiple tables are combined), plus you can use USING in JOINs.

7. Naming Patterns – DB Columns Rule 5: Use lower_case for column names. Provides consistency with table names. Rule 6: Prefixes 'n' = number of, e.g. n_items 'd' = date of, e.g. d_birth, d_create 't' = time of, e.g. t_start 'dt' = datetime of, e.g. dt_sent 'is', 'has', 'to' for booleans, e.g. is_sent, has_joined, to_check Rule 7: Suffixes units, e.g. price_aud, mass_kg, length_m, duration_s ids, e.g. customer_id, basket_id names, e.g. customer_name, country_name

8. Naming Patterns - Application-wide Rule 8: For all variables and values that match database column names, use exact same name in XHTML, CSS, JavaScript and PHP. e.g. if the database column name is first_name, then also use: XHTML: PHP: $first_name = (int)$_POST['first_name']; CSS: #first_name {color:Red;} JS: var first_name = document.getElementById('first_name').value; This will reduce errors, improve understandability and maintainability of code, and allows some nice tricks like: $rec = $rs->fetch_assoc(); extract($rec); OR: $cust = new Cust($_POST);

9. Hungarian Notation Hungarian notation means using prefixes to indicate type. 'b' = bool, e.g. $bDone 'i' = int, e.g. $iCount 'f' = float, e.g. $fRadius 's' = str, e.g. $sName Generally cumbersome and unnecessary. Does not always improve code readability or understandability. e.g. $count is obviously a number. $name is obviously a string. Good naming is better.

10. Hungarian Notation for Page Elements Rule 9: Use Hungarian notation for page elements/document objects/controls/widgets: This distinguishes them from the value they contain. JavaScript: var tbFirstName = document.getElementById('first_name'); var first_name = tbFirstName.value; PHP: $tbFirstName = new Textbox('first_name', $first_name); Some standard prefixes: tb/txt: textbox ta/txt: textarea sel: select box dsel: date selector rb: radio button rbg: radio button group cb: checkboxfrm/form: form btn: buttondiv: div

11. Naming Variables and Functions lower_case or camelCase? lower_case is a PHP/MySQL pattern. camelCase is a Java/JavaScript pattern. ProperCase is a MS/.NET pattern. Rule 10: Use lower_case and/or camelCase for variables and functions For PHP/JS vars that match DB cols, always use lower_case. For vars that refer to objects or page elements, use camelCase with Hungarian notation, e.g. $selCountry; In other cases use lower_case or camelCase as desired, but BE CONSISTENT. For function names, use either, but BE CONSISTENT so that other programmers can detect patterns in your code.

12. Function Naming Patterns What not to do: update_record() DeleteRecord() getRec() display_rec() etc. Or: $rec->Update(); $rec->delete(); $rec->getRec(); $rec->display_rec(); What to do: updateRec() deleteRec() getRec() displayRec() etc. Or: $rec->update(); $rec->delete(); $rec->select(); $rec->display(); Rule 11: Use consistent patterns Esp. within your classes and libraries, so that other programmers (and you) can learn and remember them easily.

13. Function Naming Using Parts of Speech Rule 12: Name procedural functions like verbNoun() calcRisk(), updateRec(), openDB(), washDog() Rule 13: Functions that return booleans start with verbs-to-be, e.g. 'is', 'to', etc.: isComplete(), toCheck() Rule 14: For functions that return numeric/string values use simple names, usually nouns (like mathematical functions): sqrt(), strlen() age(), integrate(), tanh(), colour(), shirtSize() i.e. we say $y = tan($x), not $y = calcTangent($x);

14. Function names prefixes Rule 15: To avoid name collisions, use prefixes for functions within libraries: mysql_query(), mysql_fetch_assoc() dtlNow(), dtlYear() OR use classes instead msqyli::query(), mysqli::fetch_assoc() DTL::now(), DTL::year() Rule 16: Use 'get' and 'set' to access private or protected attributes. get_product_id(), set_product_id() getName(), setName()

15. Classes Rule 17: Use ProperCase for class names This clearly distinguishes them from other code elements. e.g. class Database() class Customer() class Ellipse() Rule 18: Map table names to class names. Many classes match one-to-one with database tables. e.g. if the table is named customer, the class is named Customer. If the table is named basket_item, the class is named BasketItem.

16. Constants Rule 19: Name constants with UPPER_CASE. A tradition from C. e.g. MAX_N_COLOURS, COUNTRY_ID_AU Use naming patterns with constants as well: ACCOUNT_TYPE_MEMBER ACCOUNT_TYPE_ADMIN ACCOUNT_TYPE_SUPERUSER

17. Consistency Rule 20: Be consistent with abbreviations, and document them somewhere. qty = quantityamt = amounttxn = transaction cust = custcalc = calculaterec = record db = databasers = recordsetdt = datetime Hungarian notation prefixes: tb, sel, rb, cb, etc. Rule 21: Be consistent with suffixes. e.g. if you use _id as your id suffix in your database, use this throughout the app for every id. Not a mixture of _id, _ID, Id,. Rule 22: Be consistent with meaning. Don't re-use variables for different things. e.g. $cust_id = getNickname($cust_id); // don't do this If a variable with an _id suffix is an int, make it always an int.

18. XHTML Rule 23: Use both name and id attributes for form fields, and make them the same. 'id' is used by JS, 'name' is used by PHP. Rule 24: Exception – radio buttons. Use array notation. Radio buttons are grouped by the name attribute, but ids need to be unique on a page. Array notation for ids gives advantages with JS. Male Female

19. PHP tags Should you use <?php or <? ? PHP standard is to use <?php (short tags have been deprecated) However – short tags save typing, increase productivity. c.f. '<?=' with '<?php echo'

20. Conclusion Coding standards, formatting and naming patterns are important - don't neglect or leave until the end. Can save you a lot of time during implementation, debugging and maintenance. Makes your code easier to read and understand. Makes your code look professional and well- designed to other programmers. Makes your life easier. Saves you and your client lots of money.

21. Plan carefully and you will have plenty. Get good advice and you will succeed. If you have to choose between a good reputation and great wealth, choose a good reputation.

22. Ideas for next presentation Always use double-quotes for HTML and SQL strings. Use variables for constants that are often embedded in strings (e.g. $baseUrl) How to protect against SQL injection attacks. Why to avoid stored procs.