C# – What to Include in Class Documentation Header

ccommentsdocumentation

I'm looking for informative class documentation format for my Entity, Business Logic and Data Access classes.

I found following two formats from here

Format 1 

///-----------------------------------------------------------------
///   Namespace:      <Class Namespace>
///   Class:          <Class Name>
///   Description:    <Description>
///   Author:         <Author>                    Date: <DateTime>
///   Notes:          <Notes>
///   Revision History:
///   Name:           Date:        Description:
///-----------------------------------------------------------------

Format 2 

// ===============================
// AUTHOR     :
// CREATE DATE     :
// PURPOSE     :
// SPECIAL NOTES:
// ===============================
// Change History:
//
//==================================

I feel following are the basic elements

  • Author
  • Created Date
  • Description
  • Revision History

as Namespace and Class name will be there in anyway.

Please let me know your thoughts, which format is recommended and whether there is a standard way of writing revision history?

Best Answer

Most of the information you've suggested there would be found in the source repository.

The only thing you really need is the purpose section, which says what the class is there for.

Would it be tedious to look in repository every time you want to know the other information? I'd say no. How often do you care who the original author was? Or when the file was first created? Plugins (such as Ankh SVN for Visual Studio) often allow you to right click within your current file and view the repoistory log for the file, so it's not that much of a hassle to actually see this information.

Additionally, if you store the version history in a comment, this comment needs to be maintained. So over time there's a chance it could be lying to you. The source code repository automatically keeps this historical data, so doesn't need that maintenance, and will be accurate.

Related Topic