BeaverBlog

Adding descriptive comments to your code is something that everyone will always tell you to do though in reality many people simply don’t do it. Some are just lazy, some doesn’t see the need of it, some are to stressed out to do it and some things that the c# compiler will warn you about just doesn’t need commenting. Looking at the last category, things that just doesn’t need commenting, we many times find enums. Look at this as a sample.

/// <summary>
///  Datatypes used by the EXIF specification
/// </summary>
public enum ExifDataTypes
{
	UnsignedByte = 1,
	AsciiString = 2,
	UnsignedShort = 3,
	UnsignedLong = 4,
	UnsignedRational = 5,
	SignedByte = 6,
	Undefined = 7,
	SignedShort = 8,
	SignedLong = 9,
	SignedRational = 10,
	SingleFloat = 11,
	DoubleFloat = 12
}
[/csharp]
<p>What useful comments could added to this? When compiling I'm getting twelve warnings about this code not being documented though I do have a hard time finding out what I should write about each option since I feel that the names are quite self explanatory. Just adding a dummy comment to each line would get rid of the warnings but also clutter up my code which isn't really helping me. I could also tell the compiler to ignore all warnings of this type ("/nowarn 1591" when compiling) though there might be other places in my code where I want to know that I missed a comment.</p>
<p>So no luck just yet. There is however a third method to use. Going back to C there has been a way to communicate with the compiler from your code using directives called "pragmas". C# have it as well though the standard compiler (csc.exe) only understands two commands, <a href="http://msdn.microsoft.com/en-us/library/441722ys(VS.80).aspx" target="_blank" title="Check it out on MSDN">warning</a> and <a href="http://msdn.microsoft.com/en-us/library/ms173226(VS.80).aspx" target="_blank"  title="Check it out on MSDN">checksum</a>. For my problem, warning was the one I could use.</p>
<p>The code below has a pragma added that tells the compiler not to raise warnings with id 1591 (missing comments) from line 6 to line 19.</p>
[csharp]
/// <summary>
///  Datatypes used by the EXIF specification
/// </summary>
public enum ExifDataTypes
{
#pragma warning disable 1591
	UnsignedByte = 1,
	AsciiString = 2,
	UnsignedShort = 3,
	UnsignedLong = 4,
	UnsignedRational = 5,
	SignedByte = 6,
	Undefined = 7,
	SignedShort = 8,
	SignedLong = 9,
	SignedRational = 10,
	SingleFloat = 11,
	DoubleFloat = 12
#pragma warning restore 1591
}

It still gives me lots of warnings (still have some huge enums for the EXIF class that needs this) but now I have a chance of finding the real warnings and still document the parts of my code that really needs documenting.