Solved

Best practice for php comments

Posted on 2013-05-16
6
390 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
Independent Software Vendors: We Want Your Opinion

We value your feedback.

Take our survey and automatically be enter to win anyone of the following:
Yeti Cooler, Amazon eGift Card, and Movie eGift Card!

 
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

This webinar discusses:
-Common barriers companies experience when moving to the cloud
-How SD-WAN changes the way we look at networks
-Best practices customers should employ moving forward with cloud migration
-What happens behind the scenes of SteelConnect’s one-click button

Question has a verified solution.

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

Suggested Solutions

Title # Comments Views Activity
if statement malfunction 5 44
Undefined variable with $_POST in PHP 5 40
Doubt with angularJs with PHP 4 22
Where does this error come from? 8 31
Foreword (July, 2015) Since I first wrote this article, years ago, a great many more people have begun using the internet.  They are coming online from every part of the globe, learning, reading, shopping and spending money at an ever-increasing ra…
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…
The viewer will learn how to look for a specific file type in a local or remote server directory using PHP.
This tutorial will teach you the core code needed to finalize the addition of a watermark to your image. The viewer will use a small PHP class to learn and create a watermark.

752 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