Question

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() {

    }

}
?>

Answer 1

IMHO, the comment over controller’s should contain two things:

1. How do you get to this action: which request method (POST, GET, other) and what’s the URL.
2. Very brief summary of what it does (and not “how”).

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.