Question

Related to my previous question. If I define an interface I’ll comment its members. I then don’t comment the implementing class’s implementation unless there is a reason the original comment is no longer valid.

Resharper is fine with this, Visual studio claims it’s a warning.

Importantly the inherited comments are displayed through intellisense when you work with them, which is pretty much my only real concern.

What are your thoughts on this?

Thanks

Answer 1

Adding comments to your code is always a good practice. If a component is a private or internal class, and it will be always exposed via a known interface or abstract class that has all comments in place, then you may only need to comment specific things on the implementation of that class (for example if more than one person is going to look at the code, or if you happen to return to your code after a few years). That way it will be easier to understand what the code does and why. If you have enabled XML documentation to be generated when you build the project, Visual Studio will warn you for undocumented members.

I am also receiving Resharper warnings on some classes when I enable the XML documentation generation, but Resharper warns only for items with public visibility.
To shorten the documentation work, I’d recommend commenting public classes and interfaces first (especially if you are releasing a product library), and if there is enough time, the internal/private ones. If you decide not to comment the latter, just make sure you or anyone who will be working with the code will easily understand the logic and the reasons behind it.