Writing Maintainable PHP

1. Writing Maintainable PHP Laura Thomson, OmniTI PHP Quebec Conference 16th March 2007

2. Overview • Defining the problem • Basics of maintainable code • Scaling the code base • Maintaining legacy code PHP Quebec 2007

3. What is Maintainability?

4. Maintainability • Can somebody else understand your code enough to change and update it? • Can you understand your own code enough to change and update it? • Can the code be extended and adapted easily? PHP Quebec 2007

5. How do maintainability problems arise? • Lack of foresight about: • Size of the project • Time frame/future direction • Developer ignorance (a big one) PHP Quebec 2007

6. Sizing the project • For small problems write small code and be willing to write throwaway code • For big problems design before you start • The issue arises when projects grow organically • Classic problem of being unable to redevelop a prototype PHP Quebec 2007

7. Developer ignorance • Self taught and junior developers • Lack of experience with working in teams • Lack of experience with developing significant code bases • Lack of experience with other people’s horrible code • Have not yet been forced to revisit their own old code • How are they going to improve? PHP Quebec 2007

8. Basics of maintainable code (What you should already know)

9. Basics of maintainable code • Common errors • Coding standards • Version control • Developer education PHP Quebec 2007

10. Common errors • Obfuscated code (the big one) • Failure to comment appropriately • Inline functions • Side effects • Failure to read and fit in with existing code • Ignoring security (or planning to retrofit) PHP Quebec 2007

11. Obfuscated code • The worst of all common errors: • Poor naming • Seventeen layers of handoff • Misuse of define() • Reimplementation of built in functions • Failure to do the simplest thing that could possibly work • Premature optimization (and it’s virtually always premature) PHP Quebec 2007

12. Poor naming • Not just $foo, $bar function edit_item_name(itemID) { var sItemID = "edit-item-" + itemID; var oItemID = document.getElementById(sItemID); • Imagine trying to find this error in the code define('ERROR_TAG_CATEGORY', 'ERR_TAG_CTGY::Please provide a category name (or) select an existing one'); PHP Quebec 2007

13. Abusing define() define('STR_NBSP', '&nbsp;'); define('STR_BR_TAG', '<BR/>'); define('STR_BEGIN_TD', '<TD>'); define('STR_END_TD', '</TD>'); PHP Quebec 2007

14. Reimplementation of built ins function change_to_lowercase($item,$key) { global $changes; $changes[$key] = strtolower($item); } PHP Quebec 2007

15. Simplicity • First, try the simplest thing that could possibly work. <?php /** * Description: Changes the case of text within tags <> * Make sure the $argc and $argv variables are enabled. * Invoke this script on CLI as follows: * php <thisfilename.ext> file2Bparsed.ext * **/ if ($argc <= 1 || !isset($argv[1])) { die("\nPlease enter the file to be parsed\n"); } $filename = $argv[1]; if (!file_exists($filename) || !is_readable($filename)) { die("\nEnter a valid file\n"); } PHP Quebec 2007

16. Simplicity - 2 $changes = array(); $is_match = false; $fh = fopen($filename, "r"); $contents = fread($fh, filesize($filename)); fclose($fh); $pattern = "/(<(\w+)>|<\/(\w+)>)/"; if (preg_match_all($pattern, $contents, $matches)) { $is_match = true; if (!empty($matches[0])) { //change the matched elements to all lowercase array_walk($matches[0], 'change_to_lowercase'); } } if (!$is_match) { die("\nNo match found\n"); } PHP Quebec 2007

17. Simplicity - 3 $fh = fopen($filename, "w"); if (!is_writable($filename)) { fclose($fh); die("\nFile is not writable\n"); } $contents = str_replace($matches[0], $changes, $contents); $success = fwrite($fh, $contents); if ($success) { print "\nSuccessfully matched and modified.\n"; } fclose($fh); PHP Quebec 2007

18. Premature optimization • Often obfuscates code, and often done without a good rational reason to do so function foo(&$bar) {… PHP Quebec 2007

19. Coding standards • Have and use a coding standard • Don’t need to write one from scratch: PHP standards exist for PEAR and for the Zend Framework. These can be used adhoc or serve as a basis for your own • Greenfields vs legacy: virtually impossible PHP Quebec 2007

20. How not to write a coding standard • Make the rules awkward and difficult to remember • Apps Hungarian – the most abused coding style ever • Force millions of tiny files (performance hit) • Force complete OO (why not just use Java?) PHP Quebec 2007

21. Example coding standard • (Excerpts) • Formatting e.g. • Always use long form PHP tags <?php ?> • Two space indents throughout, NO HARD TABS • … • Naming • Use camel caps for OO identifiers (classnames, methods, member variables), like this: $theVarCalledFoo • … PHP Quebec 2007

22. Standard - 2 • Comments • Every file should have a header block containing at a minimum… • Single line comments are encouraged on non-obvious code. These can also be used to add "TODO", "DEBUG", and "FIXME" items • … PHP Quebec 2007

23. Standard - 3 Semantics • Declare functions and classes in library files that do not have any execution side effects besides possibly instantiating variables or defining constants. • All code should run clean with error reporting turned up to E_ALL • Try to avoid use of the ternary operator for readability • Avoid magic numbers, declare a constant • Avoid embedding PHP logic in HTML and vice versa • Use parentheses to reinforce unclear or complicated precedence. • Avoid use of global keyword • … PHP Quebec 2007

24. Version control • For any project that will take more than a week, more than one code file, or more than one developer . • And most of the others as well. • Frequent commits of conceptual changesets • Detailed commit messages (trac, while it has shortcomings, is your friend) PHP Quebec 2007

25. The code under the rug • If nobody ever notices how awful your code is, but notices if it is late what happens? • If the next guy only says “aaarrrgh” when you are working somewhere else, does it make a sound? • You need somebody other than the original author doing QA anyway • Peer review can be confronting, but valuable • Somebody overseeing commits can pick up a lot of evil … and act as a deterrent PHP Quebec 2007

26. Developer education • Don’t underestimate the importance of training. • How: • Provide code layout and design • Provide sample code • Explain what’s required • Give frequent feedback PHP Quebec 2007

27. Scaling the code base

28. Frameworks and Architectures: use and abuse • Frameworks are buzzy, and Rails doesn’t help. • Having an architecture like MVC can be a really good thing, but: • Everybody has a different idea about how this ought to be implemented • Some of the ideas are really twisted • Some make it hard to do very basic things simply • Code bloats • Which framework? • No dominant paradigm yet, ergo little help with maintainability • Have a clear, simple, architecture that is easy to add to, easy to explain to new developers, and easy to remember now or in two or five years’ time. PHP Quebec 2007

29. What do you gain from a framework? • Standard code layout for that framework • Often makes developing a prototype fast PHP Quebec 2007

30. Downside • Skills don’t transfer from one framework to another • Rapidly prototyped code not necessarily appropriate for use in production PHP Quebec 2007

31. Two kinds of frameworks • MVC style (e.g. Cake) • Component style (e.g. eZ) • Both kinds of music (e.g. ZF) PHP Quebec 2007

32. Database abstraction use and abuse • Use PDO – it’s a defacto standard • Standardize on use of prepared statements PHP Quebec 2007

33. Security • Needs to be part of the initial build • Trying to retrofit it is very hard, but also what usually happens, and new exploits need to be accounted for • Build into your architecture stages of input and output processing to encourage filtering and escaping in single locations PHP Quebec 2007

34. Documentation • For projects beyond a certain size, you start to need significant documentation • If your plan says this code will grow large, document as you go, from the start. If it’s not done at the time, it will never be done. • (Sometimes we can all be caught short) • Aim for consistent production of lightweight documentation: • Takes less time to produce (and therefore has some chance of actually happening) • Takes less time to read PHP Quebec 2007

35. Maintaining Legacy Code(or, “The Ninth Circle of Hell”)

36. Maintaining legacy code • “Hell is other people’s code.” • Anonymous, late twentieth century • Sad true facts: • You may never read all the legacy code • There will be parts of it that are broken or never used • If the original author didn’t document it, chances are you never will • If it needs a complete rewrite, chances are you won’t have time • You will have to to deal with this at some stage if you haven’t already. PHP Quebec 2007

37. Strategies • Worth spending some time to audit: • What you have in the way of documentation • The basic architecture of the code • Coding conventions if any • What is used • What is obviously broken or fragile and why • Refactor as you go, to a lightweight plan • Don’t get too ambitious. PHP Quebec 2007

38. Questions? PHP Quebec 2007