17.1. Finding Help on the WebThe Web contains a plethora of information. Remember both PHP and MySQL are open source technologies, supported by a community of developers who share their work. That means that code is readily available on the Web for your use. There may be some code glitches, but there is help on the Web when you type your query into a search engine. We prefer Google, but you can use Yahoo! or even MSN to find useful links. First of all, you should download the PHP manual available at http://www.php.net/docs. The manual is pretty cool, since you can rapidly access any page of it if you're looking for a particular function by going to http://www.php.net/function_name (you'll fill in the italicized function name you're searching for). There is also a search utility for functions, so you don't need to always fill in the full function name. One thing we haven't covered is the PHP Coding Standard. As you've probably guessed, this standard is a document that shows proper format and syntax for variable names, control structures, and much more. These format and syntax recommendations help you minimize coding errors. Currently, some sites that address this include:
We're going to do a minor recap of some of the important concepts covered throughout the book along with code examples. This is just a refresher to jog your brain into remembering a lot of the content you've already digested. 17.1.1. CommentsSome basic coding standards are comments that help you remember what your code is doing. You may need to go back and look at code you wrote several months ago. What seems straightforward now may take considerable time to discern later without leaving some meaningful explanations. Remember that PHP uses the same style for comments as C++, including /* */ and // for a single-line comment.
The comment block should include the file's description, version, author, and perhaps a copyright. It can look like Example 17-1. Example 17-1. File comments
Files should have comments, and every function should have a block comment specifying the name, parameters, return values, purpose, and last change date, as shown in Example 17-2. Example 17-2. Function comments
The first line should be a short description, with the second line providing more details. 17.1.2. FormattingWhile there are different acceptable styles for name and spacing, the most important thing is that you pick one and stick with it so that your code has consistent visual indicators to anyone who may work with it. 17.1.2.1. IndentingSome people use tabs to indent, while others use spaces. If you do use spaces, make sure you use a consistent number of spaces; for example, two for each indent. You should indent any time you use a statement that contains a block of code, such as an if statement or a for loop. This will help you tell which block a statement belongs to and match it to closing brackets (}). Indenting isn't always necessaryit's pretty much a personal preference. As you may have noticed, not all our code in this book is indented. This is our preference, since indenting or not indenting doesn't change the code. 17.1.2.2. PHP tagsYou should always use <?php and ?> to delimit your PHP code. This is the most portable and supported format. Don't use the older <? and ?> tags, as they're not fully supported and can confuse XML parsers. 17.1.2.3. TemplatingWe've used the Smarty templating system in many examples in this book. Smarty offers a nice mix between easy to use and flexible, but there are other templating systems you can use. Their use is highly recommended, as is placing the template files in a separate directory from the PHP code. Using PHP to gather and validate data, and then using a template system to display the results, maintains cleaner, easier-to-maintain code. 17.1.2.4. ExpressionsComplex expressions can be difficult to decipher, but there are some guidelines to make them easier to understand:
17.1.2.5. Function callsAdd only one space after a comma in a parameter listing, as shown below: $var = inventory($location, $category); When assigning values, place one space before and one after the equals (=) sign. You can add more spaces when assigning multiple values to make them easier to read. $count = inventory("Minneapolis","home"); $count2 = inventory("Chicago","office"); 17.1.2.6. Function definitionsFunctions should be defined with an indent after the function line, and any included code blocks, such as the if statement, should be indented again. function inventory($location, $category = 'office') { if (condition) { statement; } return $return_value; } If you have arguments with default values, place them at the end of the argument list. The return value from your function should indicate whether it was successful or whether there's a chance it may fail. function inventory($location, $category = 'office') { if (!$location) { $return_value=false; } return $return_value; 17.1.3. ObjectsObjects have general design rules to aid their design and use because of their complexity. Each object should only have attributes associated with it that are directly related to the object. Each object should have its own error handling defined so that errors don't need to propagate to higher level objects that likely don't know as much about the environment in which the error occurred. Likewise, all objects should have their own constructor methods. 17.1.4. NamingHere are some guidelines for naming:
17.1.5. Control StructuresControl structures include if, for, while, and switch. You should indent a couple of spaces for the if statement. There should be one space between the statement and the opening parenthesis for the expression. This helps differentiate them visually from function calls. For example: if ((expression1) || (expression2)) { do_something; } elseif ((expression3) && (expression4)) { do_something_else; } else { do_default; } Curly braces ({}) make reading your code easier and help reduce errors. Use them even if you have only one statement to execute in the block. Here's an example for switch statements: switch (expression) { case 1: { do_something_1; break; } case 2: { do_something_2; break; } default: { do_default; break; } } 17.1.5.1. Including or requiring PHP filesWhen you use include_once and require_once, they guarantee that the code won't be included more than once. They're smart enough to keep track of which code has been included between them: include_once('example.php'); require_once('example.php'); The above example won't include example.php more than once. Be sure to use require when your code can't continue if the file to include is missing. Optional code can and should use include. include('optional_functions.php'); |