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     :
// ===============================
// 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?

  • 8
    Revision history if you are using some form of VCS is aleady taken care of in my opinion. By placing it here it adds another place you need to remember to document, why not let VCS do it for you and keep your code documentation as concise as possible.
    – Chris
    Oct 6, 2010 at 13:26
  • 5
    Author and creation date are also handled by source control. All you need is a description. Oct 6, 2010 at 17:42

7 Answers 7


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.


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.

  • I'd up-vote this answer +100 if I could. Oct 6, 2010 at 16:54

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.


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.

  • @karianna - So you are suggesting to leave everything except class description to source control repository; but, will it be tedious to view it from repository log each time. And what if I want to create documentation file (like .chm or sandcastle)? Oct 6, 2010 at 13:05
  • @Sandy You should be able to put in certain keywords in your code comment header that your source control repository will update each time you check in. It depends on what language you are coding in and what source control repo you are using. What are you using? :) Oct 6, 2010 at 13:09
  • @karianna - I'm using Subversion; hope discussing little tech/programming won't make this closed! :-) Please let me know whether I need to post a question in SO asking how to merge log comment to particular class? :-) Oct 6, 2010 at 13:15
  • You can use $Id: $ and $URL: $, the : might be optional, I forget. Hopefully the SO overlords won't slay us for our blasphemy Oct 6, 2010 at 13:24

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).


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.


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.

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