Coding - Commenting
(Page 3 of 10 )
Why comments? Well it really isn't for you--It's for the guy that comes after you (which may in fact be you in 6 months). Don't comment every line, but do use enough comments so "the guy after you" can follow your thought processes, business logic and coding jokes.
Block
Block quotes (using the C style comments /* */) are used mostly with functions, classes or complex logic. Here you can impart lots of information and if you follow the PHPDoc formats, you can also generate HTML documentation for your classes or functions. Here is an example:
<?php
/**
* Register a temporary file or directory.
*
* When the destructor is executed, all registered
* temporary files and directories are removed.
*
* @param string $file name of file or directory
*
* @return void
*
* @access public
*/
?> |
Inline
Inline comments ( // ) allow you to clarify your logic flow in place. These comments will be your life saver when 6 months down the road you want to add a new functionality or track down a bug that keeps slipping through the cracks. I like to annotate things like validation, error handling, DB interactions and the occasional backwards logic.
<?php
class mySession
{
public function __construct()
{
// woohoo I'm a constructor that does nothing - lazy slob that I am.
}
}
?> |
Next: Coding Style >>
More Programming Basics Articles
More By lig
/ 8 
