devexp DEVelopment EXPerience, shared with the world!

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
 */