If you write C#, and you haven’t yet turned on the documentation features, you really should. Prior to C#, every team I ever worked on said, “yes, yes, we should do a better job at documentation.” But this task always fell too low on the priority list. Some developers did it, most did not, and all of the documentation fell out of date.
C# helps you write it yourself in 3 easy steps.
- Make it a COMPILER ERROR if a method doesn’t have documentation.
You really need to turn this on. Its very easy to keep your documentation up to date as you write the code. The quick compiler error reminds you, and you never miss a function anymore. If you wait, you’ll never do it, because retrofitting N methods takes too long!! Do this early. To do this in visual studio, right-click on the Project, go to Configuration Properties -> Build -> Treat Warnings As Errors. Set it to true. - Enable generation of the XML documentation file as you build
This step takes no work! Just right-click on your project and select Configuration Properties -> Build -> XML Documentation File. Set it to “docs.xml” (or whatever works for you). - Use NDoc
NDoc is a very easy to use, free utility which converts your code markup into actual documentation that looks just like MSDN. See the NDoc user guide documentation for an example, or their developer docs. Just download, install, and point it at your project and “docs.xml” file, and it will generate the docs in about 10 seconds.
Thats it.
If you’ve been programming for any length of time, you probably have some skepticism about the practicality of documentation in large software projects. But check out these 3 easy steps – I guarantee you’ll be impressed!