Commenting Code AS3 - Not being an API

Question

How should I comment a method?

What are the best practices on commenting code?

Example:

/* Checks if a color is allowed in a given point
* of the bitmapdata of the current floor
* @param value - color to be checked
* @return boolean - if color is allowed returns true, else, return false
*/
private function isAllowed(value:uint):Boolean {
 //code...
}

Is that the best way to comment a method?

I ́ve heard there ́s the use of the tag @see. What should be on this tag? I wonder if it could be something that has a relation to the method, is that right?

Thanks.

• gnat: possible duplicate of "Comments are a code smell"

Answer 1

The best way to comment a method is to follow the existing standard in the project you're working in.

In new projects where you have control, the syntax you've got above is fine.

For that particular method, renaming it to isColorAllowed() would obviate the need for any function header at all, presuming that there is no existing standard about such things.

Answer 2

Good code should be descriptive enough that it shouldn't need comments. For example the method should do one thing only and have a name that describes that purpose.

Any parameters passed in should also be properly named so that @param type comments don't need to be used.

Perfect code would be comment-free and would read almost like English.