Go Premium for a chance to win a PS4. Enter to Win

x
  • Status: Solved
  • Priority: Medium
  • Security: Public
  • Views: 396
  • Last Modified:

Best practice for php comments

Hi

I would like to know what is the best practice when commenting php function revisions. I am working on a project with some other developers and methods we have written get updated due to bug fixes and new feature additions. Sometimes its hard to understand the who did what in to a method. We are using bzr for version control system. but I would like to add the @version to a method and put a small comment to tell what I did with the method. What is the best syntax for this.

I am currently thinking to use the following

 /**
 *      Create order to disconnect service, implemented from Service_Orders_Interface
 *      @access public
 *      @return int
 *  @version 1.1 @author name @comment comments
*  @version 1.2 @author name @comment comments
 */
0
Peiris
Asked:
Peiris
2 Solutions
 
Jagadishwor DulalBraces MediaCommented:
It's Your own options you can manage format yourself as a team all member should use a standard form there is no problem in your also

/**
 *      Create order to disconnect service, implemented from Service_Orders_Interface
 *      @access public
 *      @return int
 *  @version 1.1 @author name @comment comments
*  @version 1.2 @author name @comment comments
 */ 

Open in new window


But Make it clear like

/**
*  Create order to disconnect service, implemented from service_orders_Interface
* @access public
* @return int
* @Version 1.1
* @ author name: 
* @ comment:
*------------------------------------------------------
* @What Updated??
* @Update Date:
* @version 1.2 
* @author name:
* @comment comments
 */

Open in new window

0
 
Mark BradyCommented:
Don't forget to put the revision date as well. That is very important!
I always use the method you are already using but formatted as suggested by jagadishdulal
above. What you have is fine but keet it lined up for ease of reading and get those dates put in there.

In addition to the doc blocks above each method I have a larger one at the top of the file. Finally and one of the most helpful practices is I have a change log where I keep all my bug fixes. Just a basic txt file 'change.log' that I keep in each folder so when  a bug fix is implemented I add the fix date and description/author etc to the change log.

When any of the staff are logged in as admin they can look at any webpage on the site and click the changelog link to see what updates have been made.
0
 
Lukasz ChmielewskiCommented:
You should look at this:
http://en.wikipedia.org/wiki/PHPDoc
0
Concerto's Cloud Advisory Services

Want to avoid the missteps to gaining all the benefits of the cloud? Learn more about the different assessment options from our Cloud Advisory team.

 
Ray PaseurCommented:
+1 for @Roads_Roads!
0
 
PeirisAuthor Commented:
This solve my question
0
 
Ray PaseurCommented:
0

Featured Post

Concerto Cloud for Software Providers & ISVs

Can Concerto Cloud Services help you focus on evolving your application offerings, while delivering the best cloud experience to your customers? From DevOps to revenue models and customer support, the answer is yes!

Learn how Concerto can help you.

Tackle projects and never again get stuck behind a technical roadblock.
Join Now