Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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.

share|improve this question
add comment

1 Answer

up vote 0 down vote accepted

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.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.