PHP Classes

File: coding_standards

Recommend this page to a friend!
  Classes of Paul Williamson   Simple SQL PHP 5   coding_standards   Download  
File: coding_standards
Role: Documentation
Content type: text/plain
Description: Follow these guidlines to add layers to this class
Class: Simple SQL PHP 5
PHP 5 version of a MySQL wrapper and query logger
Author: By
Last change:
Date: 18 years ago
Size: 7,580 bytes


Class file image Download
=============================== SimpleSQL Coding Standards =============================== Please follow these guidelines when modifying or adding to the SimpleSQL source. They are slightly modified PEAR ( coding standards. Indenting and Space ===================== Use an indent of 1 tab. After the first non-tab character on a line, spaces should be used for whitespace. There should not be any space at the end of a line. Control Structures ===================== These include if, for, while, switch, etc. Here is an example if statement, since it is the most complicated of them: if ((condition1) || (condition2)) { action1; } elseif ((condition3) && (condition4)) { action2; } else { defaultaction; } 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. Format switch statements in this way: switch (condition) { case 1: action1; break; case 2: action2; break; default: defaultaction; break; } Function Calls ===================== Functions should be called with no spaces between the function name, the opening parenthesis, and the first parameter; spaces between commas and each parameter, and no space between the last parameter, the closing parenthesis, and the semicolon. Here's an example: $var = foo($bar, $baz, $quux); 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); $long_variable = foo($baz); Function Definitions ===================== Function declarations follow the "one true brace" convention: function fooFunction($arg1, $arg2 = '') { if (condition) { statement; } return $val; } Arguments with default values go at the end of the argument list. Always attempt to return a meaningful value from a function if one is appropriate. Here is a slightly longer example: function connect(&$dsn, $persistent = false) { if (is_array($dsn)) { $dsninfo = &$dsn; } else { $dsninfo = DB::parseDSN($dsn); } if (!$dsninfo || !$dsninfo['phptype']) { return $this->raiseError(); } return true; } Comments ===================== Inline source documentation should work with phpDocumentor. More information about PHPDoc can be found here: Non-documentation comments are strongly encouraged. A general rule of thumb is that if you look at a section of code and think "Wow, I don't want to try and describe that", you need to comment it before you forget how it works. C style comments (/* */) and standard C++ comments (//) are both fine. Use of Perl/shell style comments (#) is discouraged. Including Code ===================== Anywhere you are unconditionally including a class file, use require(). Anywhere you are conditionally including a class file (for example, factory methods), use include(). Note: include() and require() are statements, not functions. You don't need parentheses around the filename to be included. PHP Code Tags ===================== Always use <?php ?> to delimit PHP code, not the <? ?> shorthand. This is required for PEAR compliance and is also the most portable way to include PHP code on differing operating systems and setups. Strings and Arrays ===================== Always use '' for strings that don't contain variables. For strings that contain variables, either close the string and concatenate the variables, or use double quotes. Array keys are strings and should be quoted as such. Put braces around the variable to prevent the parser from reading it as "Array['key']" Valid ways to use strings and arrays: $foo = 'Single quotes (\') work fine when escaped'; $foo = 'I am showing you ' . $bar['baz'] . ' an example'; $foo = "I am showing you {$bar['baz']} an example"; Invalid ways to use strings and arrays: $foo = "There are no variables in this string."; $foo = "The key is $bar[baz]"; Header Comment Blocks ===================== All source code files in the core SimpleSQL distribution should contain the following comment block as the header: /** * SimpleSQL * Copyright (c) 2001-2003 Paul Williamson <> * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License * as published by the Free Software Foundation; either version 2 * of the License, or (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * $Id **/ Note: Add another $ after $Id. It must be documented this way to prevent CVS from adding a version string into this documentation file. Example URLs ===================== Use "" for all example URLs, per RFC 2606. Naming Conventions ===================== Generally speaking, the names of classes, functions and variables should always be descriptive enough to easily tell the reader of the code what they are used for. Classes ===================== Classes should be given descriptive names. Avoid using abbreviations where possible. Class names should be all-lowercase. Functions and Methods ===================== Functions and methods should be named descriptively with underscores separating words, all-lowercase. A verb-noun combination is recommended. Some good function names: connect() get_data() build_some_widget() Constants ===================== Constants should always be all-uppercase, with underscores to separate words. Constants are preferred over magic numbers. Global Variables ===================== Don't use global variables in any file with a class. True, false, null ===================== PHP's built-in values true, false and null must be written in lower-case. Compatibility ===================== All code must work with PHP 4.0.0. If this isn't feasible, check availability with function_exists(). Don't bother coding for PHP3. All code must work with all possible configurations of PHP, including various values for register_globals, magic_quotes_gpc, etc. All HTML must work as intended in all popular browsers, including Internet Explorer 5+, Netscape 4+, Mozilla, and recent versions of Opera. Do not use JavaScript to validate forms or supply critical features. JavaScript should supplement the existing HTML, not replace PHP. All code must work with JavaScript enabled or disabled, in all popular browsers, as feasible. Queries should be valid for all available databases. Use a switch() statement to determine the database type if you need features available only to certain databases. Queries should work with recent and popular versions of databases. For MySQL, keep it compatible with all versions newer than 3.22.x. Keep all code compatible with all web servers, primarily Apache and IIS. $Id: CODING-STANDARDS.txt,v 1.3 2003/08/23 14:43:28 paul Exp $