C# Comments – Where to Place Comments, Class Declaration or Constructor?

ccomments

For a given class, where should the comments about the purpose of the class go?

/// <summary>
///       <----------------- describe the class here (1)?
/// </summary>
public class Message
{
  ...
  //class members here
  ...
  /// <summary>
  ///      <--------------- or here (2)?
  /// </summary>
  public Message()
  {
  }
}

If I go with the first option, the purpose of the class is very easy to find when I open the file, it's in the same place, on approximately the same line. When you have lots of classes, this is easier for the eyes. You don't have to scroll down past the members to find the constructor

If I go with the second option, I get Intellisense when creating an object of the class, stating it's purpose and explaining the parameters, which is very nice.

From what I can tell, I can't get both advantages by using just one method. The only solution I can think of is putting the same comment in both places, but that's just duplicate information and I don't like it.

Best Answer

The purpose of the class should be described above the class name.

A documentation above the constructor is to document differences between the different constructors of the class and what the parameters passed to the constructor(s) do.

Related Topic