PHP Commenting Standards

Email generation templates and user comment boxes are commonly written in PHP.

PHP is an open source HTML scripting language, the code of which is run by the PHP interpreter. Comments are treated as white space and ignored the PHP interpreter when it compiles and runs the code. Programmers add comment lines to code so others know the intended function of each section of code. Comments are also a standard method to troubleshoot code.

Software Code

Placing a hash or pound sign at the start of a line causes the PHP interpreter to ignore any text following it. Placing two right-facing slashes - // - after a line of code creates an inline code comment. All text after the two right-facing slashes on that line are ignored by the PHP interpreter. The PHP interpreter will skip to the next line looking for executable code. A multi-line comment block is indicated by /*...*/. The multi-line comment does not require additional identifiers until its end marked by the following: */ . Any PHP code inside the multi-line comment block will not be executed. There is no standard on the length or number of single comment lines or multi-line comment blocks used in PHP code.

Commenting Standards

Comments should describe the intended function of the code. Comments should provide a high level explanation of the logic used. Comments can explain the manipulation of variables or data sourced called by the code. Adding blank lines before comment lines separates it visually from the code, which makes it easier for programmers to find and read. Adding a space before the first letter after the double slashes improves readability. Inserting a blank comment line after a block of comments is optional.

Troubleshooting

Commenting lines removes them from the executable logic. Commenting out lines of code pinpointed as potential causes of trouble allows programmers to identify the specific code generating the error. Software developers should comment out a suspected section and rerun the transaction. If the error reoccurs, programmers remove the commenting from the tested lines of and comment out the next suspected set of code. This process is repeated until the error does not recur. The commented code is then fixed, the commenting marks removed, and the fixed code is tested.

Drupal Comments

Drupal uses PHP files for Web page templates. PHP code files end in .php. Drupal's comment template is called comment.tpl.php. Comment.tpl.php provides a standard template for processing comments on web pages. The PHP commenting template contains code for including HTML links inside comments and digital signatures. Editing templates in Drupal is done in PHP. Web developers using Drupal can reference PHP templates for standard actions like email generation.

References

• "PHP: The Good Parts: Delivering the Best of PHP"; Peter MacIntyre; 2010
• "PHP Programming with MYSQL"; Don Gosselin, Diana Kokoska, Robert Easterbrooks; 2010
• "Beginning PHP 5.3"; Matt Doyle; 2011
• "Drupal's Building Blocks"; Earl Miles, Lynette Miles; 2011
• "How to Do Everything: Facebook Applications"; Jesse Feiler; 2008
• "Pro Drupal Development"; John K. VanDyk; 2008

Resources

• "Pro Drupal 7 for Windows Developers"; Brian Travis; 2011
• "Beginning Drupal"; Jacob Redding; 2010
• "Beginning PHP and MySQL: From Novice to Professional, Fourth Edition"; W. J. Gilmore; 2010