How To Document PHP Code

On This Page Introduction Naming Conventions Comments Block Comments File Comment Block Function Comment Block Curly Braces Whitespace No Magic Numbers Introduction Programming style is about how you organize and document your code. Style is more than a matter of aesthetic interest. A program written following a consistent style is easier to read, easier to correct and easier to maintain. This course follows the industry-standard PHP Coding Standards of the PEAR Manual. Exceptions to this standard are contained in this document. Some portion of the grade for most programming assignments is based on conformance to these standards. ^ top Naming Conventions Use Meaningful Names Choose names that suggest their purpose. Good names help you understand the problem you are solving. Variable Names There are two commonly-used styles you may use. However, you must be consistent and only use one of them in a program. The instructor's preference is the first style. Start with a lower-case letter and use uppercase letters as separators. Do not use underbars ('_'). $myVar Use all lower case letters and use underbars ('_') as separators. $my_var Constant Names Use all capital letters and use underbars ('_') as separators. define("DEFAULT_PAGE", "/index.html"); Function Names Start with a lower-case letter and use uppercase letters as separators. Do not use underbars ('_'). function myFunction() Class Names Start with an upper-case letter and use uppercase letters as separators. Do not use underbars ('_'). class MyClassName ^ top Comments Comments are explanatory notes for the humans reading a program. With good name choices, comments can be minimal in a program. The only required comments are block comments at the beginning of each file and before each function declaration. Block comments are described in the next section. One other time to add comments, other than block comments, is when your code is unusual or obscure. When something is important and not obvious, it merits a comment. Block Comments PHPdoc is a program that examines the declarations and documentation comments of your code to produce a set of HTML pages. These pages describe your code to other programmers. For an example of the documentation produced, see PHPDOC 2000/12/03. The documentation comments are derived from block comment, which you create as follows: Indent the first line to align with the code below the comment. Start the comment with the begin-comment symbol (/**) followed by a return. Start subsequent lines with an asterisk *. Indent the asterisks with an additional space so the asterisks line up. Separate the asterisk from the descriptive text or tag that follows it. Add a description of the purpose of the class or function. Insert a blank comment line between the description and the list of tags, as shown. Insert additional lines to create various tags. The last line begins with the end-comment symbol (*/) indented so the asterisks line up and followed by a return. Note that the end-comment symbol contains only a single asterisk. /** * Create link text. * * @param $url Link href string * @param $text Text string to display * @return Link with text in HTML tag form */ For more information on the tags, see the CcDoc Directives. File Comment Block Every source file must have a comment block at the top containing the course number, assignment number, name of the file and purpose of the file. One or two lines is usually sufficient to explain the purpose. In addition, you must add the author tag containing your name and the version tag containing the date the assignment is due. For example: /** * CIS-165PH Asn 6 * hello.php * Purpose: Prints a message to the screen. * * @author Jane User * @version 1.0 8/20/02 */ The following tags must be used always: @author: your name. @version: the current version number and date of the software Function Comment Block Every function must have a comment block before the function. For example: /** * Read a line of text from the shell console. * * @return A String input by the user. */ The first line is a description of how to use the function. Where appropriate, the following tags must be used: @param: name of the parameter a function receives and what values are permitted. @return: describe the return type and permissible range of values. ^ top Curly Braces A fervent issue of great debate in programming circles is placement of curly braces. Either of the following two styles is acceptable in this course: Place the initial brace on the same line as the keyword and the trailing brace inline on its own line with the keyword: if (condition) { while (condition) { ... ... } } Place brace under and inline with keywords: if (condition) while (condition) { { ... ... } } The first style is the PEAR standard and the preference of the instructor. When Braces are Needed All if, while and do statements must either have braces or be on a single line. This helps to make sure someone adding a line of code does not forget to add braces. ^ top Whitespace Always layout your source code so that elements that are part of a group go together. No Tab Characters Do not have any tab characters in your source code. It is difficult to impossible to read source code if your tab settings are different than the authors. The easy way to remove tabs is to set your text editor to substitute the correct number of spaces for a tab character. In Textpad, this is available under the Configure => Preferences menu. From the dialog window that appears, expand Document Classes and C/PHP to find the Tabulation settings. Check both of the check boxes: Convert new tabs to spaces Convert existing tabs to spaces when saving file Press the OK button to apply the changes. Spacing Around Operators Always put spaces before and after operators. This improves the readability of expressions. For example: int c = a * b - d; Indentation Always indent within curly braces. Use 3 or 4 spaces for each indentation level, but be consistent. For example: function myFunc() { if (something happened) { if (another thing happened) { while (more input) { ... } } } } if-else-if-else Formatting Always line up if statements with their associated else statement. Beyond that, there are two common styles that you may use: Place the initial brace on the same line as the keyword and the trailing brace inline on the same line as the next statement. For example: if (condition) { // Comment ... } else if (condition) { // Comment ... } else { // Comment ... } Place brace under and inline with keywords. For example: if (condition) // Comment { ... } else if (condition) // Comment { ... } else // Comment { ... } The first style is the PEAR standard and the preference of the instructor. ^ top No Magic Numbers A magic number is a numeric literal that is not defined as a constant. It's magic because no one has a clue what it means after 3 months, including the author. From widespread use, -1, 0, 1, and 2 are not considered magic numbers. Instead of using numeric literals, use a constant. Because of their special meaning, write constants in all upper case and use underbars ('_') as separators. define("DEFAULT_PAGE", "/index.html"); For information on writing PHP constants, see Chapter 8. Constants of the PHP Manual. ^ top Home | WebCT | Announcements | Course info | Expectations | Schedule Project | Help | FAQ's | HowTo's | Links Last Updated: December 11 2005 @22:05:49