Self Documentation in C#

Writing code is not the same as writing documentation. Both instances require a different mindset. Yet in the software development world, we all know that documentation is just as important. In large projects, coordinating multiple developers requires having a common language and a common understanding of the system. Documentation whether it is design or specification, plays a key role in bringing different minds into a single cohesive thinking machine.

For decades the most common form of self-documentation in source code is the comment. Some developers write more than others. I remember the days when written documentation was non-existent and my only recourse was to embed the program flow in comments. There were instances a few months later that the comment was a lifesaver.

In C#, comments comes in three forms. The first form of comment was inherited from C and is called the multi-line or block comment. Basically a multi-line comment is almost a free form comment and anything enclosed between /* and */ is ignored by the compiler. C programmers would use the block comment for file headers and function headers. The following is an example of both headers.

Sample of header file comment.
/*
--------------------------------------
My Corporation Limited
Copyright (c) 2001, All rights reserved

File: program.c

Description:
Mary had a little lamb and it was white as snow.

Revision History:
Rev Date Who Description
1.0 01/01/01 John Initial Draft
--------------------------------------
*/

Sample of function header comment.
/* --------------------------------------
* float fnCalculateSomething()
*
* Description:
* Mary had a little lamb and it was white as snow.
*
* parameters:
* paraAmount double
* paraTotal double
*
* returns:
* newTotals double
* --------------------------------------
*/

Feel free to use these comments for your own use.

When C++ came into the picture, it introduced a new style of comment - single line comments. You can now write comments on the same line as your code. This makes reading source code a lot easier. In C++, having two slashes denotes a single line comment (//). The following is an example of a single line comment in C++.

// Description:
// Mary had a little lamb and it was white as snow.
//
float fnCalculateSomething( double paraAmount, double paraTotal )
{
float newTotal; // declaration
newTotal = paraAmount + paraTotal; // formula for calculating totals
}

C# supports both types of comment style, with the addition of a third style of commenting. The third style of commenting is based on XML and the Microsoft C# compiler can generate an XML file based on the tags within the comments. A C# comment is closer to the C++ comment in that it is also a line comment and requires three slash (///).

Go To Page: 1 2

Articles in this Topic    Discussions in this Topic