Pro .NET 2.0 Code And Design Standards In CSharp (2006) [eng]
.pdf
86C H A P T E R 4 ■ C O D E D O C U M E N TAT I O N
•Require all developers to be trained in documentation.
•Consider incorporating documentation as part of the design and development phases of a project.
•Sign off on documentation and subject it to peer group and or an independent technical review (e.g., by an external IT auditor).
•Categorize documentation as code design and code development documentation. (Note that development includes code maintenance.)
•Consider housing the documentation where it is accessible to application architects and developers (e.g., Visual Studio solution) and stored safely (e.g., Visual SourceSafe).
■Tip Write a policy as a set of pragmatic statements rather than as a lengthy dialog.
Where
A code documentation policy is used by all of the development teams.
Why
A documentation policy minimizes the risk of knowledge degradation.
How
A policy is the result of a consultation process among stakeholders (project managers, application architects, and developers). Once agreed on, it may be distributed as part of a documentation manual (online and/or manual).
The Standard: Development Documentation Policy
The standard acknowledges the importance of knowledge retention and that a documentation policy may be used to minimize the risk of knowledge degradation.
Documentation of Code
When documenting, code is separated into two categories: (1) code design and (2) code development. The separation recognizes the inadequacy of relying solely on code comments; although they do document code development, however, they do not document the underlying code design strategy, rationale, and structure.
C H A P T E R 4 ■ C O D E D O C U M E N TAT I O N |
87 |
Code Design Documentation
Documenting code design refers to identifying how and why the code has been designed the way that it has been.
What
Documentation of code design discusses code from a design perspective. It briefly explains the underlying strategy, rationale, and structure used in developing the code and highlights critical aspects of the design. What items are documented is a matter of site policy—for example, critical aspects only; identify design patterns used; identify important classes and their respective roles; explain design choices; identify critical dependencies; identify code fragility; and list key assumptions, and so forth. What is best documented will evolve over time, and in that regard, the adequacy of documentation may be discussed regularly in team meetings (including a discussion of a program to verify the adequacy of respective documentation).
Where
Code design documentation should be readily accessible for developers and application architects.
Why
Code design documentation enables a team to retain and share critical design knowledge that identifies and explains the underlying intention of the developers and application architects.
How
Design documentation may be written in a log file (see the section Code Design Log, later in this chapter), which may be a txt, html, or xml file and stored in a Visual Studio solution, for example. To ensure format consistency, the log may be copied from a template.
The Standard: Code Design Documentation
The standard acknowledges the importance of documenting code design so that it readily identifies and explains key aspects of the underlying code design strategy, rationale, and structure.
Code Design Log
A code design log is a simple form of documentation that is readily accessible to be referenced and updated.
What
A design log is a register in which key design information is stored. It contains documentation about modification history, assumptions, fragility, and a profile of key classes and types, for
88 C H A P T E R 4 ■ C O D E D O C U M E N TAT I O N
example. It may be used at solution level or folder level (e.g., UI Class folder and Utility Class folder would each contain a code design log, which documents the classes within each respective folder).
Where
A design log resides in each Visual Studio solution and/or folder that stores code.
Why
A design log is an intuitive and quick method to document design; it supports a note format that minimizes the time demands on developers and application architects. It puts the documentation where it is most convenient for application architects and developers to reference.
How
A template is prepared as a txt, xml, or html file and copied to each Visual Studio folder in which code is written. The following is a template of the contents of a code design log; it may be modified to suit the requirements of a development team (subject to policy):
---------------------
Code Design Log
---------------------
----------------
Log Header
----------------
Log Filename: AlgorithmAssembly
VS Solution: ModelT.Enterprise Log Purpose: List major issues
Note: Item format: Number, [Date of Entry; Author's email address], Comment.
--------------------------
Modification History
--------------------------
1. [01/10/05; petern@modelt.com] Code classes: A,B,C,D,E.
2. ...
-------------
Overview
-------------
[01/10/05; stevek@modelt.com] All algorithms are coded in "algorithm" classes, which are subsequently contained in client classes.
2. ...
-----------------
Assumptions
-----------------
1. [01/10/05; andrewb@modelt.com] Monetary precision is to the nearest dollar. 2. ...
C H A P T E R 4 ■ C O D E D O C U M E N TAT I O N |
89 |
-------------------------------------
Type Roles and Relationships
-------------------------------------
1. [01/10/05; billb@modelt.com] EngineAssemblyAlgorithm has seven classes which participate in this algorithm (A,B,C,D,E,F,G). Class C is the controller class, while class A and B ...
2. ...
--------------------
Design Patterns
-------------------
1. [01/10/05; sammyc@modelt.com] Strategy Pattern (Classes A,B,C..F); (Class A, B, C, D, E);
2. ...
---------
Types
---------
----------
Classes
----------
1. [01/10/05; sammyc@modelt.com] Class 'AC' is an abstract controller class (MVC). A controller
class is used to manage algorithm worker classes and view and data requirements. 2. ...
----------
Structs
----------
1. [01/10/05; sammyc@modelt.com] Struct 'B' represents the attributes which comprise an
engine. An abstract class has not been used in this instance because...
2. ...
-----------
Interface
-----------
1. [01/10/05; billb@modelt.com] IAccessory represents the base interface for the hierarchy
of accessory types. 2. ...
----
...
----
90 C H A P T E R 4 ■ C O D E D O C U M E N TAT I O N
The Standard: Code Design Log
The standard acknowledges the use of a code design log as an intuitive and quick method to document code design. It may be prepared as a txt, xml, or html template and stored inside a folder within a Visual Studio solution, for example.
Documentation of Code Development
There are four types of documentation of code development commonly used: line comments, block comments, XML comments, and object browser comments.
Line Comment
A line comment uses a delimiter (e.g., "//") to signify that the line of code is a comment line and is not part of the compilation.
What
The line comment is a comment that takes up all or part of a single line in a code module (e.g., class or code file). Where a comment requires more than one line, several line comments may be stacked line after line, as an alternative to a block comment.
Where
A line comment is placed above a line of code with no line space between the comment and the code, and one or no spaces between the delimiter and the start of the comment. A line comment may also be placed at the end of a line of code.
Why
The line comment is a convenient way for a developer to document or signify something that is noteworthy about a line or block of code.
How
A line comment may be placed above a line of code, specified as:
// Note: integer is used and not double. int noTires;
or a line comment may continue over multiple lines:
//Note: integer is used and not double -- car has five tires,
//which includes the spare tire. Write Property setter code to limit
//the number of tires to five, per car.
int noTires;
C H A P T E R 4 ■ C O D E D O C U M E N TAT I O N |
91 |
or a line comment may be placed at the end of the line of code:
int noTires = 0; // always assign a default value
The Standard: Line Comment
The standard acknowledges the use of the line comment, which may be used as a single line comment, a multiline comment, or an end-of-line comment.
Block Comment
A block comment uses an opening and closing delimiter to identify a block of comments.
What
The block comment is a multiline comment used for large comments running over multiple consecutive lines.
Where
A block comment is placed above the block of code with no line spacing between the last line of the comment block and the first line of the code.
Why
The block comment is a convenient way for a developer to document or signify something that is noteworthy about a block of code.
How
A block comment uses opening ("/*") and closing ("*/") delimiters, which may be specified as:
/*
The following block of code manages data access to a SQL Server database. The code, below, is wiring which leverages the data access classes, which are referenced from the ModelT.Enterprise.DataManager DLL. Note that data access classes rely on the file ConnectionString.XML which resides in the 'Data' folder. If you need to modify the connection string, then do so using that file.
*/
DataSet ds = new ModelT.Enterprise.DataManager.Open("DS", "spSalesHistory");
...
The Standard: Block Comment
The standard acknowledges the use of the block comment where documentation is extensive. However, it notes that Visual Studio’s line comment tool may be a more convenient method to comment blocks.
92 C H A P T E R 4 ■ C O D E D O C U M E N TAT I O N
XML Comment
An XML comment is a supplement to the line and block code comments. Using an add-in tool (e.g., Visual Studio XML Documentator), XML comments can be published to an HTML page and object browser.
■Caution Visual Studio 2005 Beta 2 and RC were used in preparing this book. At that time the XML Documentator tool was not available. The discussion and following example use the tool in an earlier version of Visual Studio. It is noted, however, that a freeware XML Documentator tool is available at http://ndoc.sourceforge.net.
What
The XML comment is a single line or block of XML comments, visible within or external to a code module—unlike a line or block comment, which is not visible outside of the code module.
Where
An XML comment is placed above a line or block of code with no line spacing between the XML comment and the first line of code.
Why
The XML comment is a convenient way for a developer to publish documentation externally. Note, however, that XML comments can be verbose.
How
An XML comment uses a comment delimiter, which may be specified as:
///<summary>
///Note: integer is used and not double -- car has 4 tires.
///</summary>
int noTires;
or a line comment to carry a comment over more than one line:
///<summary>
///Note: integer is used and not double -- car has five tires,
///which includes the spare tire. Write Property setter code to limit
///the number of tires to five, per car.
///</summary>
int noTires;
C H A P T E R 4 ■ C O D E D O C U M E N TAT I O N |
93 |
■Note Visual Studio automatically inserts “<summary>” and “</summary>” tags, when you key in the xml delimiter ("///").
The Standard: XML Comments
The standard acknowledges the use of XML comments as a form of internal and external code documentation.
Object Browser Comments
An object browser comment is a comment that resides in Visual Studio’s object browser window (refer to Figure 4-5 for a screenshot of object browser comments).
What
The object browser comments is a type of documentation that Visual Studio automatically publishes in object browser as part of the process of using the XML Documentator tool.
Where
An XML comment is placed immediately above the signature of a type or a member of a complex type.
Why
An object browser comment is a valuable form of type documentation because it publishes the documentation in the IDE, which makes it readily accessible for developers and application architects.
How
An XML comment is placed immediately above the signature of a type or a member of a complex type definition. An object browser comment uses an XML delimiter, which may be specified as:
///<summary>
///Note: integer is used and not double -- car has 5 tires.
///</summary>
int noTires;
or over more than one line:
///<summary>
///Note: integer is used and not double -- car has five tires,
///which includes the spare tire. Write Property setter code to limit
///the number of tires to five, per car.
///</summary>
94 C H A P T E R 4 ■ C O D E D O C U M E N TAT I O N
The Standard: Object Browser Comments
The standard acknowledges the use of object browser comments as a form of internal and external type documentation, and notes that it conveniently publishes the documentation in the Visual Studio IDE, which makes it readily accessible for developers and application architects.
XML and Line/Block Comments
Should XML comments replace line/block comments? Although XML comments have great advantages (e.g., they are easy to publish to object browser or HTML pages), they do have a minor downside: they can be verbose—which may or may not be okay—and they cannot be tagged onto the end of a code line. So, there will be situations where you may want to use all three comment tools rather than put everything in an XML comment.
What
XML and line/block comments are documentation methods that serve different purposes (discussed earlier). When used in a partnership, they offer the developer a rich choice of tools.
Where
XML comments may be used whenever documentation needs to be published externally; otherwise line/block comments may be more convenient.
Why
Because XML comments tend to be verbose, there are times when line/block comments are a more appropriate choice for a small comment (e.g., at the end of a code line).
How
XML and line/block comments may be combined to document code development, as in the following example:
namespace ModelT.Enterprise.Vehicle
{
/********************************************** In this code file is the definition of enumerators,
Car and Radiator.
**********************************************/
//Enumerators - leave a blank line else the XML comment
//is ignored by Visual Studio
///<summary>
///Note: that there is only one color
///on offer.
C H A P T E R 4 ■ C O D E D O C U M E N TAT I O N |
95 |
enum CarColor
{
Black
}
///<summary>
///Car class is used to instantiate a Model T
///car, regardless of model type.
///</summary>
public class Car
{
// Private fields int _wheels;
}
public class Radiator
{
// Private fields
private double radiatorCapacity;
// Methods
///<summary>
///Call FitRadiatorCap() to
///fit the radiator cap to the
///radiator.
///</summary>
public void FitRadiatorCap()
{
;
}
// Properties
///<summary>
///Radiator capacity, represents
///maximum number of pints of water.
///</summary>
public double RadiatorCapacity
{
get {return radiatorCapacity;} set {radiatorCapacity = value;}
}
}