Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question
3  
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 '10 at 13:26
    
Author and creation date are also handled by source control. All you need is a description. –  Mike Seymour Oct 6 '10 at 17:42
add comment

6 Answers

up vote 10 down vote accepted

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.

share|improve this answer
    
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)? –  Coder Hawk Oct 6 '10 at 13:05
    
@Sandy - yes, only have the description. See my update to see why I think that's all that's necessary. –  David_001 Oct 6 '10 at 13:24
    
+1, didn't see you sneak in there 1 minute earlier, apologies for duping your answer! –  Martijn Verburg Oct 6 '10 at 13:25
    
thank you –  Coder Hawk Oct 8 '10 at 4:29
add comment

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.

share|improve this answer
    
I'd up-vote this answer +100 if I could. –  Chris Holmes Oct 6 '10 at 16:54
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
    
@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)? –  Coder Hawk Oct 6 '10 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? :) –  Martijn Verburg Oct 6 '10 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? :-) –  Coder Hawk Oct 6 '10 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 –  Martijn Verburg Oct 6 '10 at 13:24
    
@karianna - thank you –  Coder Hawk Oct 8 '10 at 4:29
show 1 more comment

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

share|improve this answer
add comment

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.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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