Why spend the time to comment your code?

As a programmer we spend our time writing code from simple one line scripts to complex applications. No matter what the size adding comments and documenting your code adds to the longevity of your project.  The reason I say this is that if you write a library to perform a certain set of operations or to interact with a protocol or app you have a choice to spend the time adding in comments or to get it down faster you could leave them out.  Lets say a year goes by and all of a sudden the interface you integrate with has been upgraded. You or those that utilize your code are now faced with a dilemma:  update the existing code, or rewrite from scratch.  If you had taken the time to well document your code then their is a better chance that your code will be updated as you or the developers should be able to easily find the elements that need to be modified or replaced. Also by well documenting your code in an open source environments allows the code to be easily enhanced or debugged for a users particular needs.

In-line commenting

In-line commenting is the placement of comments inside of function calls to describe what action the line is performing.  This type of commenting is up to the programmer on how much needs to be included. Some programmers choice to only comment sections that contain obscure functionality or special cases, others prefer to comment every line. Myself, I find that their is a balance to be drown in describing what a section of code performs in addition to any critical pieces.

// executes the curl request
$result = curl_exec($ch)

File, Class, Method, and Property Documenting

Arguably documenting on the method, property, and class level is the most important aspect of documentation.  By well documenting these elements a user can quickly and easily know what functions they need to interact with and how to go about using the various classes.  phpDocumentor is the standard auto-documenting tool for the php language. It functions similar to javadocs in that you write comment block headers for functions, parameters, classes, and php files the describe what the elements purpose is and the various parameters that go into it.

For example a method comment block would contain a description of the method, any parameters that are expected, return value information, and also details on any Exceptions that could be thrown. For a full list of all available tags you can review the tutorial at phpDocumentor’s main website

/**
* Method for importing existing schema to Doctrine_Record classes
*
* @param string $directory Directory to write your models to
* @param array $databases Array of databases to generate models for
* @param array $options Array of options
* @return boolean
* @throws Exception
*/
public static function generateModelsFromDb($directory, array $databases = array(), array $options = array())
{
    return Doctrine_Manager::connection()->import->importSchema($directory, $databases, $options);
}

Conclusion

Commenting makes it possible for other programmers from beginners to advanced to easily review and understand your code. To further help users phpDocumentor has the ability to build and export customizable html pages that can be used by users as a reference for utilizing the code without looking at the source code. This is extremely helpful for users of libraries that only need to know how to use the code and not how it actually works. How to install and use the doc builder is outlined in the phpDocumentor tutorial.