1

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:

  • Has anyone done anything like this? How?
  • Are there other ways to solve the XML doc dilemma?
  • My concern is that it will slow down team member who need to work on existing undocumented code, who would need to do some code-archeology to be able to check in even small changes. Any thoughts on preventing that?
tobre
  • 1,347
  • 3
  • 21
  • 53

1 Answers1

1

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
H H
  • 263,252
  • 30
  • 330
  • 514
  • I thought about this option too. The disadvantage is that you have to add Xml documentation headers to all public members yourself. This is why the Stub idea came about. – tobre Oct 18 '15 at 11:30
  • The general idea is that you will have to do some typing. Then the initial `///` to trigger the snippet isn't that much trouble. – H H Oct 18 '15 at 12:20