What should I include in my class documentation header

Question

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?

Answer 1

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.

Answer 2

Have descriptive class, method, and variable names. This will eliminate the need for such comments as purpose and description. Sometimes we think that the shorter the method name the better. On the contrary, make a method name as long as you want as long as it clearly describes its purpose. Only have notes that are absolutely vital and help code understanding in some specific way. When making changes to code, programmers often forget to update comments. You can end up with comments and code being out of sync and doing more harm than good.

Read this article by Jeff Atwood - Coding Without Comments.

Answer 3

I use standard tags to generate documentation. Nothing more, nothing less. See here

I never put information which doesn't belong to class. Author, data, revisions are data to store on a Version Control System.

The two formats presented are useless to generate documentation and has the biggest error on comments, they list the revision history.

Answer 4

Much of this information can be added by your source control repository, leaving you really only with description, which should accurately describe the scope and behaviour of the class. I'd recommend taking a look at some of the Javadoc for the Java JDK as an example.

Answer 5

Everything in that list is unnecessary. Your source control should take care of nearly everything, and what it doesn't cover is taken care of by good naming conventions.

If I have to read your "Description" to figure out what your class is doing then either (a) your named it poorly or (b) you wrote a bad class that is doing too much (SRP).

Answer 6

I've been playing around with changing out my header templates since, as others point out, a lot of this information can be found in the repository and so far the big fields that I've been looking to keep are the following:

• Description - What is being done by the code.
• Notes - Anything that needs to be known about the code that is not easily derived from the comments in the code itself.
• References - Any references that the code is dependent upon that are not made clear though the use of include or similar statements.

One item that may also be useful to include is a section on Keywords While you might be able to do a search for function, class, struct, etc names, there might be some keywords that the other names in the file do not make clear. Or for older, poorly documented code, it might be the first step in documenting the code for maintenance.

Answer 7

Most of the other answers i read so far assumed that there is only one repository that is always available

Since sourcecode can loose the connection to the repository (i.e. if copied) my class documentation goes like this:

• class documentation header (= the comment block at the beginning of of the file) only contains required legal infos (i.e. copyright by xyz under gpl-licence)
• everything that a developer that uses the class should know should go into the class-java-doc-comments (or the .net equivalent of it) so that modern ide-s can show this info as tooltip info ins sourcecode that uses the class.

---

You can also add the ticketnumber for the bugfix or feature-request so you may have some clue where/when/why the class was created (if you are lucky enought that you can still access the tickets after a few years).

When beeing asked to fix problems in old closed-source legacy programs the ticket numbers where quite valuable for me to understand the original requirements of the code.