CODEWITHSUNDEEP
c#coding-styleresharperxml-documentationghostdoc
tobre
tobre

Reputation: 1405

Solving the XML doc comment dilemma

Regarding XML doc comments in C#-code there are two schools of thought:

  1. Robert C. Martin's Clean Code approach of "If you carefully name your
    classes, methods and variables to express the intent of your work,
    you don't need comments."
  2. You need to comment every public class, interface, method and property

Since programmers are lazy, many use tools like GhostDoc or Resharper to automatically generate XML doc comments. The intention of these tools was to provide a basic comment, which can be easily extended by the programmer. However, reality shows that many generated comments remain unchanged. Therefore they add no value to the code in terms of clarity or maintainability. Unchanged generated XML doc comments are just noise. In a way, they are a form of a DRY principle violation.

In my team, we realize that uselessness of these "noise-comments". However we don't want to go all the "no comments at all" way either. An idea that came up was to generate stubs like this for all public members:

/// <summary>
/// TODO
/// </summary>

The build (we use TFS2013) should break, if someone checks in code with the TODO comments untouched.

My questions are:

Upvotes: 1

Views: 256

Answers (1)

Henk Holterman
Henk Holterman

Reputation: 273824

There already is a built-in provision, though not ideal:

  • don't use comment generators
  • don't use your proposed stubs
  • compile with Warning-Level = 4
  • check the [x] Xml documentation file
  • check the [x] Treat Warnings as errors

Upvotes: 1

Related Questions