Comments

Some 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 unless you leave some meaningful explanations. Remember that PHP uses the same style for comments as C++, including /* */ and //.

Remember, every file you create should start with a descriptive comment block.

The comment block should include the file's description, version, author, and perhaps a copyright. It can look like Example 18-1.

Example 18-1. File comments

* this file is about furniture stores.

* this file is about furniture stores in Minnesota, Wisconsion, Iowa and Illinois.

* Portions Copyright 2008-2009 (c) O'Reilly Media, Inc.

* The rest Copyright 2009 (c) from their respective authors

* @version $Id: coding_standards.html,v 1.2 2009/12/19 24:49:50

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 18-2.

Example 18-2. Function comments /*

* furniture stores locator.

* Locate furniture stores in Minnesota, Wisconsion, Iowa and

* Illinois based on their zip code.

* @author michele davis [email protected]

* @param zipcode the zipcode to search for stores near

* @return store the store id of the nearest store

The first line should be a short description, with the second line providing more details. Example 18-2 is in PHPDocumentor format, which defines a standard for how to document source files. For more information, visit http://manual.phpdoc.org/ HTMLframesConverter/default/.

Was this article helpful?

0 0

Post a comment