I'm quite heavy handed when it comes to commenting my code.
As well as inline comments, I always have a config comment at the top of every file.
In addition to basic information such as Author, Filename, when the file was created, I use Subversion to get information such as: the current revision, when was the file last updated, who updated the last file.
To automate the process, I have a CFEclipse snippet that is saved as a template (require separate ones for both CFM and CFC files). So when I create a new file, I create it from the template, and this runs the snippet automatically, prompting me to fill in certain information. You can see the snippet below.
<!---
Filename: $${CURRENTFILE}
Creation Date: $${DAYOFMONTH}/$${MONTH}/$${YEAR}
Original Author: $${author}
Revision: $Rev$
$LastChangedBy$
$LastChangedDate$
Description:
$${description}
Methods:
$${methods}
--->
Once I commit this file to Subversion, the Subversion properties are populated, meaning I end up with something like below.
<!---
Filename: weatherProxy.cfc
Creation Date: 18/July/2007
Original Author: Andy Allan
Revision: $Rev: 45 $
$LastChangedBy: allana $
$LastChangedDate: 2007-07-18 12:24:59 +0100 (Wed, 18 Jul 2007) $
Description:
This is our proxy CFC, which in turn calls the Yahoo weather CFC as part of Ray Camden's Yahoo API package.
The component works by first being init'd, recieving a list of towns to which we have to retireve weather. At the moment this is passed in, but in time we will retrieve this information from a database as it will match all the locations for the company.
On init, we call getWeather() passing it the list of towns, and this method loops through the towns returning the weather data for each and storing in an Application
variable structure.
We then use getMyWeather() which accepts a town as an argument to return the weather data specfic to that town.
Methods:
init: This is our constructor method, which MUST be called before any other method. It takes a single
argument "datasource" and returns itself.
getWeather: private function that loops through all the companies locations, getting their weather data and storing the data in an Application structure.
getMyWeather: method which returns the weather for a specific town.
--->
To get Subversion to actually populate your comments you need to assign a new property to every file/folder in your application.
You can either do this by running the following command:
propset -R svn:keywords "Rev LastChangedDate LastChangedBy" /pathToFiles/trunk
Or from within CFEclipse, simply right click your Project folder and choose "Team" > "Set property" and then add the new property as indicated in the image below.
With every commit, you'll now see the most up to date Subversion information directly in your comments.
