I always ask this to myself, and I think it's time to hear some opinions, what should I put in the comments of my methods that represent certain actions?
I should explain what? Comment on what?
Currently I do not comment on anything because I do not know what to put.
Edit:
You are not understanding what I asked, probably because I have not explained well, I want to know what to put in the comments of methods that represent an action (action of a Controller). Example (in PHP):
<?php
class UserController {
/**
* What to put here?
*/
public function editAction() {
}
}
?>
IMHO, the comment over controller's should contain two things:
POST, GET, other) and what's the URL.The thing is, you should not need to write a paragraph of details, because you function name should already state what it does (which in Controller actions is somewhat limited by convention, thus the second point). And the containing code should be short enough for easy skipping though and verbose enough to explain "how" part.
There is actually a video [51:20] related to the subject. Though, i think UncleBob's rule about 3..5 lines is a bit too harsh. There is a lot of preparations in controllers action, but ~4 lines, which do the actual work, should be enough.
First of all, don't write comments to tell what the method does.
There are two reasons for this, first, it makes everything cluttered with comments and is harder to read than the code just by itself. Comments like this
i++; //increment i
are pointless. Second, these comments will become outdated when you maintain the code, and maintaining comments is excessive busy work that you don't want to be doing. If you write so many comments that you have to maintain them, the comments will become actively harmful because they do not correspond to what the code does
i-= 2; //increment i
Your goal should be to write clear, understandable code with descriptive names so that people can read it without having to rely on comments.
If you do comment your methods, document what the purpose of the method is, do not document how the method does what it does--that's what the code does. You should comment things that are not obvious to people reading the code, you should comment on what the code is supposed to do, but just remember to steer clear of commenting on the low-level details of the code.
If you don't know what to put for a method's comment, that often suggests you don't fully understand what you want the method to do. Otherwise, you would be able to describe it.
Think of it this way. Imagine that you put the application away for 2 years and then looked at it again. Describe to your future self what this method should do.
I like to ram pack my comments with as much information as humanly possible so when later my entire program stops working I can go back and find out what a function is doing, why it's doing it, and why it isn't doing something else. The downside is, as others have pointed out, it means you have to update your comments every time you update your code. However, as long as your comments are helpful, this is a valid cost.
/**
* There are several different states which all DisplayObjects can *
* be in. The majority of these are mouse events (over, out, click, *
* press, release, scroll...), some are keyboard events (key press, *
* key release, shift...) and the rest are implementation specific *
* (ie. animations, cleaning the screen). Display objects which are *
* created use these constants to create indexed Graphics objects, and *
* then indexed cached canvases. Doing so allows for hot swapping of *
* one context (ie. OVER) for another context (ie. OUT). This provides *
* considerable performance increases (at the cost of increased memory *
* and increased initial load times). Also, this provides a unified *
* model of graphics. Therefore, Text, Shape, or Bitmap instances can *
* all be created differently and rendered differently (via the child *
* class specific render() function), then cached onto a back end *
* canvas, at which point, they are all drawn onto the main canvas in a *
* similar fashion. *
* @property _contextID
* @protected
* @type Object
**/
var contextCounter = 0;
contextID = {
ANIMATION : contextCounter++,
DEFAULT : contextCounter++,
CLEAN : contextCounter++,
CLICK : contextCounter++,
CLIP : contextCounter++,
COLLISION : contextCounter++,
DBLCLICK : contextCounter++,
DBLLDRAG : contextCounter++,
DBLLDRAGGING : contextCounter++,
DBLRCLICK : contextCounter++,
DBLRDRAG : contextCounter++,
DBLRDRAGGING : contextCounter++,
DRAG : contextCounter++,
DRAGGING : contextCounter++,
DROP : contextCounter++,
ENTER : contextCounter++,
INVALID : contextCounter++,
INVALIDDROP : contextCounter++,
LDRAG : contextCounter++,
LDRAGGING : contextCounter++,
LEAVE : contextCounter++,
LPRESS : contextCounter++,
LRELEASE : contextCounter++,
MOTION : contextCounter++,
RCLICK : contextCounter++,
RDRAG : contextCounter++,
RDRAGGING : contextCounter++,
RPRESS : contextCounter++,
RRELEASE : contextCounter++,
SCROLL : contextCounter++,
SCROLLIN : contextCounter++,
SCROLLOUT : contextCounter++,
TRPLCLICK : contextCounter++,
TRPLLDRAG : contextCounter++,
TRPLLDRAGGING : contextCounter++,
TRPLRCLICK : contextCounter++,
TRPLRDRAG : contextCounter++,
TRPLRDRAGGING : contextCounter++,
VALID : contextCounter++,
VALIDDROP : contextCounter++
};