Still celebrating National IT Professionals Day with 3 months of free Premium Membership. Use Code ITDAY17

x
?
Solved

Best practice for php comments

Posted on 2013-05-16
6
Medium Priority
?
394 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 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
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.

 
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

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.

Question has a verified solution.

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

Developers of all skill levels should learn to use current best practices when developing websites. However many developers, new and old, fall into the trap of using deprecated features because this is what so many tutorials and books tell them to u…
This article discusses how to create an extensible mechanism for linked drop downs.
Explain concepts important to validation of email addresses with regular expressions. Applies to most languages/tools that uses regular expressions. Consider email address RFCs: Look at HTML5 form input element (with type=email) regex pattern: T…
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…

721 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