Skip to main content
Post Made Community Wiki by Warren P
Source Link
Kramii
  • 14.2k
  • 5
  • 47
  • 64

Leave them out!

Normally, it is good practice to remove comments where the information expressed in them is already present elsewhere. If you can express the purpose of a method clearly and unambiguously by giving it a good name then there is no need for a comment.

Put them in!

Your example illustrates two exceptions to this rule:

First, "UpdateLocation" may (depending on context) be ambiguous. In that case, you either need to give it a better name or provide a comment to remove the ambiguity. Improving the name is generally the better option, but this is not always possible (when you are implementing a published API, for example).

Second, the "///" in C# indicates a comment that is intended to be used to auto-generate documentation. The IDE uses these comments to tool-tips, and there are tools (Sandcastle) that can generate help files and so forth from these comments. As such, there are arguments for inserting these comments even if the methods they document already have descriptive names. Even then, however, many experienced developers would frown on the duplication of information. The deciding factor should be the needs of those for whom the documentation is intended.