How Do You Write Class Header Comments?

Commenting, even though it is the bane of my existence, is important when doing your SharePoint development. No commenting is more important (IMHO) then doing your class header comments since sometimes when you are hungover (which I am doing this morning, and while I do this blog post I don’t remember what the hell I did last night) writing code you write some silly stuff that doesn’t make a lot of sense to other developers. While line commenting is nice and great, if you have good naming conventions combined with good header comments it is generally enough for a developer who knows his ass from a hole in the ground to make sense of your code.

Regardless, I am interested in how other people do their header comments. It looks like MSFT does their header comments like this:


// ===============================
// ===============================
// Change History:

I think that is ok. I write mine differently though because that is too many lines. I don’t like lines.


///   Namespace:     
///   Class:         
///   Description:   
///   Author:                             Date:
///   Notes:         
///   Revision History:
///   Name:           Date:        Description:


How do you do your header comments?


2 thoughts on “How Do You Write Class Header Comments?”

  1. I use XML comments so that Intellisense help is enabled for my code, and so that I can create alternate documentation types using tools like NDoc. This keeps the documentation embedded in the code and increases the likelihood that it will be written and kept up to date.

    Also, I avoid repeating what is already present in the file or other sources. For example, the following headings in your example are repeated elsewhere:

    Namespace – The code
    Class – The code
    Author – Source control
    Date – Source control
    Revision history – Source control

    That leaves notes and description, which the XML comment format handles. It’s the DRY (don’t repeat yourself) principle applied to comments.

Leave a Reply

Your email address will not be published. Required fields are marked *