Good commenting practice in PHP.

rayhan — Thu, 26 Jun 2008 06:50:06 +0000

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.

My First application on CakePHP

rayhan — Tue, 14 Aug 2007 05:32:20 +0000

Developing an application using CakePHP is a big challenge specially for those who are new to cake. And this is my case. I was encouraged to develop my next application on cake trying some tutorials. But when I started my application which is a employee management system for a university I found a lot’s of problem.

Most of them are due to my inconvenience with cake and some of them are due to cake’s auto framework. But I am solving all problems as I am required to submit my project according to a deadline. Though I already missed a deadline.

However, this the not the problem, the problem is I am confused about the way I am solving problems. Am I following the standard or not. Cause if I go wrong way during development then it will trouble me during maintenance. I am always confused that cake may have a better way to solve this problem.

I think this is a unique problem for all cake novice.

Rayhan's blog (raynux.com) » CakePHP

Good commenting practice in PHP.

My First application on CakePHP