Solved

Best practice for php comments

Posted on 2013-05-16
6
392 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
[X]
Welcome to Experts Exchange

Add your voice to the tech community where 5M+ people just like you are talking about what matters.

  • Help others & share knowledge
  • Earn cash & points
  • Learn & ask questions
6 Comments
 
LVL 15

Accepted Solution

by:
Jagadishwor Dulal earned 250 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 250 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
PeopleSoft Has Never Been Easier

PeopleSoft Adoption Made Smooth & Simple!

On-The-Job Training Is made Intuitive & Easy With WalkMe's On-Screen Guidance Tool.  Claim Your Free WalkMe Account Now

 
LVL 110

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 110

Expert Comment

by:Ray Paseur
ID: 39212962
0

Featured Post

On Demand Webinar: Networking for the Cloud Era

Did you know SD-WANs can improve network connectivity? Check out this webinar to learn how an SD-WAN simplified, one-click tool can help you migrate and manage data in the cloud.

Question has a verified solution.

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

Part of the Global Positioning System A geocode (https://developers.google.com/maps/documentation/geocoding/) is the major subset of a GPS coordinate (http://en.wikipedia.org/wiki/Global_Positioning_System), the other parts being the altitude and t…
Build an array called $myWeek which will hold the array elements Today, Yesterday and then builds up the rest of the week by the name of the day going back 1 week.   (CODE) (CODE) Then you just need to pass your date to the function. If i…
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 count occurrences of each item in an array.

630 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