Chapter 50. Documenting the Source Code

One of the most common programming rules states that documenting the source code is fundamental. This is of course the truth but you have to think about the way source code is commented. Classical comments are useful to explain what code does so that you can easily remember how your code works if you need to retake it after a long time, or they can help other developers to understand your code. But this is not the only way of documenting code in .NET development. A sophisticated environment such as Visual Studio offers the IntelliSense technology that not only speeds up the way you write code but is also shows instructions on how you use objects and members. This is possible because of special kinds of comments that you can add to your code, known as XML comments. Such comments allow writing the source code documentation, explaining objects’ and members’ behavior, and also providing descriptions and examples that can be shown up by IntelliSense. But that is not all. Documenting code with XML comments is particularly important if you develop reusable compiled libraries and allow automating the process of building compiled documentation files (such as .chm files) in a similar way to the MSDN documentation. In this chapter you learn to use XML comments to provide simple and complex source code documentation, also learning how to build compiled documentation.