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:

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

How do you do your header comments?

Article Or Research Filed Under General (Personal).

---

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

   Comment by Brad Sokol — August 3, 2007 @ 11:13 am

2. 

   Hi,

   How do we go about getting a blog on the SharePoint community portal ?

   Thanks

   Comment by sharepoint — January 1, 2009 @ 5:46 am

RSS feed for comments on this post. TrackBack URL

Leave a comment

Name (required)

Mail (will not be published) (required)

Website