?
Solved

Best practice for php comments

Posted on 2013-05-16
6
Medium Priority
?
398 Views
Last Modified: 2013-06-01
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
Comment
Question by:Peiris
6 Comments
 
LVL 15

Accepted Solution

by:
Jagadishwor Dulal earned 1000 total points
ID: 39173535
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
 
LVL 20

Assisted Solution

by:Mark Brady
Mark Brady earned 1000 total points
ID: 39174429
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
 
LVL 27

Expert Comment

by:Lukasz Chmielewski
ID: 39175996
You should look at this:
http://en.wikipedia.org/wiki/PHPDoc
0
Free Tool: Subnet Calculator

The subnet calculator helps you design networks by taking an IP address and network mask and returning information such as network, broadcast address, and host range.

One of a set of tools we're offering as a way of saying thank you for being a part of the community.

 
LVL 111

Expert Comment

by:Ray Paseur
ID: 39179082
+1 for @Roads_Roads!
0
 

Author Closing Comment

by:Peiris
ID: 39212948
This solve my question
0
 
LVL 111

Expert Comment

by:Ray Paseur
ID: 39212962
0

Featured Post

Free Tool: Subnet Calculator

The subnet calculator helps you design networks by taking an IP address and network mask and returning information such as network, broadcast address, and host range.

One of a set of tools we're offering as a way of saying thank you for being a part of the community.

Question has a verified solution.

If you are experiencing a similar issue, please ask a related question

3 proven steps to speed up Magento powered sites. The article focus is on optimizing time to first byte (TTFB), full page caching and configuring server for optimal performance.
It’s a season to be thankful, and we’re thankful for users like you who engage on site, solve technology problems, and network with others in the industry. What tech are we most thankful for? Keep reading.
Learn how to match and substitute tagged data using PHP regular expressions. Demonstrated on Windows 7, but also applies to other operating systems. Demonstrated technique applies to PHP (all versions) and Firefox, but very similar techniques will w…
The viewer will learn how to create and use a small PHP class to apply a watermark to an image. This video shows the viewer the setup for the PHP watermark as well as important coding language. Continue to Part 2 to learn the core code used in creat…
Suggested Courses

601 members asked questions and received personalized solutions in the past 7 days.

Join the community of 500,000 technology professionals and ask your questions.

Join & Ask a Question