PHP ''Tutorials'' - Commenting 
PHP Tutorial Index

Commenting


Commenting is often neglected by young programmers but its importance is great. Even if you write the code yourself, you likely will forget what it is doing next time you look at it - even if you're still working on the same project.

The bit below will try to illustrate a code file for you:

<?php
/*
File: filename.php
This is the 'heading' comment. It says the file does this task, whatever it is.
Sometimes, I will outline the required data and the basic flow of the program here.
*/

$aVariable = ''; // this is a 'line' comment.
$anArray = array(); // line comments tell you what the code to the left is doing.
$o = ''; // this is the output variable.

foreach($anArray as $key => $value)
{
// this is a 'block' comment. it reminds me what this whole block of code does
if ($key >= 5)
preg_replace('/^.*\\.[a-z].\d*$/', 'something', $value); // sometimes, a line comment is needed even where there is a block comment. because some lines of code are ridiculous to decipher a week/month/year later!
$o .= $key.': '.$value.'<br/>'."\n";
}
print($o);
?>

The code above demonstrates three types of commenting I like to use. Heading, line and block comments.
Heading comments are always at the top of the file. It tells you what the file is called and what it basically does or will do. Writing a heading comment at the start saying what the purpose of the file is, and what the file needs to do will keep your aims for that code together in your head. If you start coding something that doesn't fall into what the aim or task of the file is then it probably doesn't belong in there. The filename is good in case somehow your file gets renamed. You can still identify what that file is by the heading comment.

Line comments I use generally when the flow of code gets a bit complex. If you have to do a lot of data checking with series of nested if() statements and a few for/switch/whiles along the way, using line comments can help track what each closing bracket is for. Line comments also help with lines that will commonly be hard to understand later. Regular expressions are a good example of this.

Block comments I find get used the least, but can be helpful. Usually when I begin a new file and have the heading comment done I will then do a few comments to show me what I need to code. For example:

<?php
/*
File: addRecord.php
This file will add the user's input to the database.
Data required:
SESSION['userLogin'] - ensure user is logged in
GET - form data
SESSION['tableName'] - ensure tableName is set
Basic flow:
check session data
verify user data
build INSERT statement
execute SQL query
handle errors
*/

// check session data
// verify user data
// build INSERT statement
// execute SQL query
?>

Once I have done this, I can start creating the code for this task (insert user's data into database). The first bit of code I would do is code to check the session data. As I write the code, the other 3 block comments (verify user data; build INSERT statement and execute SQL query) will get pushed down the file waiting for me to code them. Once data verification coding is done, I have the comments below to remind what to do next. I would then code something to verify the user's data etc. until all the block comments are handled.
There is no block comment for handling of errors because I find most error handling I do is done along the way to ensure the program doesn't work on any data it shouldn't.


That's about it for a little bit on comments. The only other thing I can suggest is to keep the alignment or positioning of your comments consistent. This will increase the readability of your files.

PHP Tutorial Index