Notes on methods
A method should be accompanied by a comment that says what the method does. This is the specification of the method. The comment has to be precise and clear. A potential user of the method should be able to look only at the comment and the list of parameters to know how to use it; they should not have to look at the list of instructions.
Example: When you want to bake a cake, you look at the title of a recipe, a short description, and the list of ingredients to determine whether you want to use that recipe --not the list of instructions to bake it.