Comments to the max
I was wondering around on the big wide scary web and saw a lot of badly written comment for code so I thought it shouldn’t be bad to give a little overview on how comment should be written, at least how I think it should be written.
Not all comments can be written in the same way and not all comments can be read by other programs but I personally think the Java comment is the most readable one, and (huge advantage) can be read by the Javadoc processor. When writing in PHP this is done in the same way as PHPDoc is an adaptation of Javadoc.
So write your comment like this:
/** * This is a basic description of your method, * write down here what the function does in general * *@param integer $id *@return array Array of objects *@author Kenneth van Rumste */
As you can see we have the general description of a method first, written in a few words. Only write more if this is really necessary. Comments are there to help when the developer doesn’t understand the code and everybody should keep in mind that the name of a method should contain the basic information about what’s happing inside. For example don’t use methodName1 for a method, but retrieveDailyUsers to select the daily users. So you don’t need a lot of extra comment to explain what is happening, Jeff Atwood (Coding Horror) wrote a great post last year on the usage of comments.
In the second part you can see a bunch of tags added into the comment, these are very handy when writing code as they inform parsers how to display documentation and allow IDE to define variable types.
I added only the basic data to the comment and a lot more tags can be added but as I m a lazy guy you can check them all out here.
To finish this post let us take a look at some of my all time favorite, comment jokes
stop(); // Hammertime!
Catch (Exception e) {
//who cares?
}
Exception up = new Exception("Something is really wrong.");
throw up; //ha ha
doRun.run(); // ... "a doo run run".
long long ago; /* in a galaxy far far away */
/////////////////////////////////////// this is a well commented line
//Abandon all hope yea who enter beyond this point
//Woulda
if(x) {}
//Shoulda
else if(y) {}
//Coulda
else {}
/* This isn't the right way to deal with this,
but today is my last day, Ron just spilled coffee on my desk,
and I'm hungry, so this will have to do... */
return 12; // 12 is my lucky number
#define TRUE FALSE //Happy debugging suckers
// TODO - Comment this function
Comments