2

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.

  • you put it at the class (option 1), this is the expected place for most documentation generators – ratchet freak Feb 20 '14 at 11:42
  • Yes, Doxygen puts the comment in the docs with option 1, and that's nice. But VS won't give me any info when creating an object of the class, which I get with option 2, and which I also like. – mihai Feb 20 '14 at 11:53
  • possible duplicate of Why are /// comment blocks important? – gnat Feb 20 '14 at 12:01
  • 2
    @gnat, I'm already using the /// comment blocks. I just don't know where to put them. I've changed my code example to better reflect this. From the selected answer: [..]They can essentially see all the documentation for your method or class without having to go to the file itself to figure out what it does. Yeah, problem is, I can't if I'm choosing the (1) method, as ratchet freak sugested – mihai Feb 20 '14 at 12:19
  • 2
    For c# you put class description in (1) while in the constructor you explain what that constructor does. You might want download and run StyleCop it has some warning on documentation too. For example constructor documentation should start with: "Initializes a new instance of the <see cref="YourClassName"/> class." Note some StyleCop suggestion are somewhat invasive, but at least they give you the idea on what documentation might look like. – Fabio Marcolini Feb 20 '14 at 12:23
11

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.

1

A slightly devil's advocate position:

Neither position.

The name of the class should tell the reader its purpose. If it doesn't, find a better name.

  • this does not answer the question asked – gnat Feb 21 '14 at 5:54
  • @gnat On answering the question, Is “Don't do it” a valid answer? - I am sure you will have seen these and more... – AakashM Feb 21 '14 at 9:12
  • sure: 'consider also to answer the actual question, too. As in *"Don't do it because of A, B and C. But if you decide to do it anyway, I would follow this approach:..."*' – gnat Feb 21 '14 at 10:22
  • 1
    Sure, comments can be an antipattern, and good naming is vital. It's great when good naming can replace comments, but "no comments" is an ivory tower rule. Almost all programming languages, while extremely expressive, are fixed by a spec with strict syntax. It's often more concise and readable to use natural language to express concepts in a comment, especially when commenting for structured docs like JavaDoc, Doxygen, or Sphinx. (Also, what happens when you're forced into a poorly named framework or library? EX: Uncommented Swing projects are almost completely unmaintainable.) – kdbanman Jul 9 '15 at 20:00

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.