Code Leader: Using People, Tools, and Processes to Build Successful Software

4.8. Documentation in Place

The last step in ensuring that done is really done is putting your documentation in order. What that means in practical terms will differ, depending on what platform you are using to write your code. It might mean updating a word processing document with documentation about your new code, including how to use it and what problems consumers might encounter. It might mean updating formal electronic documentation such as a .chm compiled help file. Or it could mean updating a wiki or other interactive electronic source.

In .NET, it might mean making sure that your XML Documentation comments are properly in place. In C#, you can use comments with the marker /// and XML markup to embed documentation directly into your code. The following is an example of how to use XML comments to document a small class:

/// <summary> /// This class demonstrates a better way of dealing with /// dependencies and exception handling. /// </summary> public class BetterErrorHandling { IFileReader _reader; /// <summary> /// Constructs a BetterErrorHandling class using /// the specified IFileReader interface. /// </summary> /// <param name="reader">An IFileReader for reading files.</param> public BetterErrorHandling(IFileReader reader) { _reader = reader; } /// <summary> /// Reads the file at the specified path as a single string. /// </summary> /// <param name="path">The path of the file to read.</param> /// <returns>A string containing the contents of the file.</returns> /// <exception ...