Should you XML Comment on private methods?

Question

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?

Answer 1

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.

Answer 2

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.

Answer 3

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.