14

So I use XML Comments in my code to help explain Public Methods and Public Members, another developer has mentioned that not all of my methods have XML Comments. I use the rule, if public or protected, add XML comment, if private, don't.

Does this sound logical or is there some reason why you would XML Comment a private method?

Rodders
  • 2,425
  • 2
  • 20
  • 34
  • 4
    I personally (try to) comment all my methods, regardless of their access modifiers. Usually private methods perform more important operations and are likely the place you need to go if something needs to be changed. You don't write comments just for people using your classes, but also for yourself. – Andrei V Oct 09 '13 at 09:33

5 Answers5

13

There are no strong rules about comments, but I believe that it is good to comment public/internal/protected methods.

Sometimes I comment private methods when they are not very clear. Ideally code should be self-documented. For example if you have a method like 

Item GetItemByTitle(string title)

then it is not required to write comments, because it's clear enough. But if a method could be unclear for other developers, please put your comments or rename/refactor the method event if it's private. Personally I prefer to read code, not comments :) If you have too many comments code becomes hard to read. My rule is to use comments only when it is required.

If on your project you have a convenience to document all methods including private methods, then follow this rule.

Shamim Hafiz - MSFT
  • 21,454
  • 43
  • 116
  • 176
Warlock
  • 7,321
  • 10
  • 55
  • 75
7

It makes sense to also comment private and protected members - possible reasons include:

  • another developer may need to use the code and a consistent commenting approach can prove helpful;
  • you may want to auto-generate a help/documentation file of the source code at some point; in this case, lack of Visual Studio XML comments can result in a lot of undocumented code.

I don't really see a good reason why you would limit XML comments to public members.

w128
  • 4,680
  • 7
  • 42
  • 65
3

I subscribe to the guiding philosophy that a method should be simple enough that its signature describes exactly what it does. That being said, this is not always possible (especially when working with legacy code) so there are situations when a header comment is useful. Such as:

  • The methods use is not obvious (and cannot easily be refactored)
  • To generate api documentation

I don't think are really any hard and fast answers here, if it feels right to comment it then comment it

codemonkeh
  • 2,054
  • 1
  • 20
  • 36
3

I always take it as a good practice to comment all my methods as equivalent to having to explain them to someone, as I would want to have them explained to me if I did not carry knowledge as to what is happening, and why.

We develop in a small team, and this really does help with team development. More so, I regularly use my OWN comments, to figure out what the heck my though process was 3 months ago when I look at a piece of code.

Absolutely worth it to spend some time in adding comments to the top of your methods / procedures that do some interesting stuff.

Louis van Tonder
  • 3,664
  • 3
  • 31
  • 62
3

The question is a little unclear as to whether you are asking:

  1. Should private code be commented in general? or
  2. Assuming you do what to comment private code should you use XML or standard C# comments?

To comment or not

To answer the first question, needing to comment any code is a bit of a code smell. When you run into a situation that you run across code that is hard to read an needs explaining, your first attempt to solve that should be to change (usually by renaming things) so that the code is more readable. Using comments to explain an unclear method name should be a last resort.

There are some exceptions. Public methods of DLLs shared outside the solution should always be commented.

I recommend reading Robert C. (Uncle Bob) Martin's "Clean Code" book for more details on this.

XML or C# comments

In general, yes use XML comments for methods as opposed to C# comments. The XML comments show up in intellisense. Also, the XML comments are bound to the method and if you use refactoring tools to move methods the XML comments will be brought along with the method, whereas C# comments can easily be separated from the method.

One reason not to use XML comments is if you will be publicly distributing your DLL and the XML comment file. The XML file will contain comments for all your internal and private methods. So just make sure that you're OK with your customers potentially reading any of those comments on private methods.

Timothy Klenke
  • 814
  • 1
  • 10
  • 21