Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. Join them; it only takes a minute:

Sign up
Here's how it works:
  1. Anybody can ask a question
  2. Anybody can answer
  3. The best answers are voted up and rise to the top

How should I comment a method?

What are the best practices on commenting code?


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



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?


share|improve this question
possible duplicate of "Comments are a code smell" – gnat Dec 22 '14 at 10:28
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

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.

share|improve this answer

Your Answer


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.