Rayhan’s blog (raynux.com)

Rayhan’s Personal Web Blog Site

Entries Comments


Good commenting practice in PHP.

26 June, 2008 (12:50) | CakePHP, PHP, programming, Reference

Tags: ,


Currently I am working on the documentation of my software written in PHP. From this documentation project I have found that proper commenting of code is a good documentation. If you write your code base along with comment then you don’t need to worry about the API Documentation of your software. You just have to use some software like PHPDoc or Doxygen to make the API in a minute. Specially I am using Doxygen in my project which is also used in CakePHP API documentaiton.

When you are commenting your code be careful to meet the commenting requirement/procedure so that those documentation software can understand your comment as a data.

Here is a simple example what Doxygen can easily parse for you.

    	
/**
 * Class A.
 * 
 * Class description.
 * 
 * @example example here.
 * @todo to do here
 * 
 * @package appname
 * @subpackage appname.subname
 * @author yourname
 * @since version 1.0
 */
class A extends Object{	
	/**
	 * Enter description here...
	 *
	 * @var type
	 */
	var $member1;	
	/**
	 * Enter description here...
	 *
	 * @param integer $param1
	 * @param string $param2
	 * @param array $param3 contains a array of data
	 * @return boolean
	 * @since version 2.0
	 */
	function doSomeThing($param1, $param2, $param3){		
		return true;
	}
}
    

So if you follow the commenting technique carefully, you don’t have to white API of your own.

«

  »

Comments

Comment from dewa
Time: March 13, 2009, 8:32 pm

i’m using ci now, more easier…

Write a comment