This is something that has bothering me for a while now. I guess there are a couple of obvious important things that should go into a comment, such as:
- A description of the parameters (and their types, if we are in a dynamic language)
- A short description of what the method does, e.g. "Trims leading and trailing white-spaces for unlimited length strings."
- If it throws exceptions.
- Semantics of the return value.
But one could image all kinds of information that could be added to such a comment, for instance:
- Usage examples
- Explanation of how the method is used in the project scope
- TODOs / Nice to haves for this method which are not yet implemented
- And probably many more
Now my question is, how do you write a really good method or class comment (that is, what information do you put in it, and how do you make sure it is kept up-to-date), with just the right amount of information so that any developer who has to work with your code is up to the task, but considering the fact that as you add more and more information to your comment, the probability for it to become outdated rises (e.g. if I add pointers to where the method is / will be used in the project, it could be replaced in that location or it might very well never be used, even though it was intended to).