![\"\"](\"http:\/\/www.insomnihack.com\/wp-content\/uploads\/comment_your_code_rant.jpg\" "\\"Comment")
<\/a>Cut the next poor bastard a break and comment your code.<\/p><\/div>\n
To be clear, I’m not talking about comments in the body of a method itself. I’ve found that if the body of a method requires more than a few comments to describe what it’s doing, that method probably needs to be refactored. I’m talking specifically about the XML comments (or JavaDoc comments in the case of Java source code) of the public and protected members of my non-private classes.<\/p>\n
This post describes the tools I use on a regular basis to produce good code documentation. These tools are primarily targeted towards C# developers working in Visual Studio. I may do another post later to describe tools useful for recreating this process in other languages and platforms. If you’re a VB.NET programmer, there’s a good MSDN article<\/a> on XML comments in Visual Basic you might want to check out.<\/p>\n GhostDoc<\/a> is a free Visual Studio add-in originally created by Roland Weigelt<\/a>. It was recently acquired by SubMain<\/a>, but they’ve stated that it is their intention to keep it free.<\/p>\n \n Configuration screen for GhostDoc<\/p><\/div>\n Visual Studio 2008 already helps a little with XML documentation by inserting the tags for you when you type three forward slashes (i.e. \/\/\/) and hit Enter.<\/p>\n [csharp] GhostDoc does you one better by filling out the empty XML comment tags with text based on code element type, parameters, name, and other contextual information. The default keyboard shortcut is Ctrl-Shift-D. You can also get at GhostDoc via the context menu.<\/p>\n [csharp] Usually, a bit of modification to the comments generated by GhostDoc is all I need.<\/p>\n Agent Smith<\/a> is a C# coding style validation plug-in for ReSharper<\/a> hosted on Google Code<\/a>. You need to have ReSharper installed in order to use it. In addition to naming validation and smart paste, Agent Smith provides some valuable features for writing XML commenting including comment validation, re-flow, and spell check.<\/p>\n Agent Smith - Code Style Settings<\/p><\/div>\n Agent Smith - Naming Convention Settings<\/p><\/div>\n Agent Smith - Spell Check Settings<\/p><\/div>\nGhostDoc<\/h3>\n
<\/a>
\n\/\/\/ <summary>
\n\/\/\/
\n\/\/\/ <\/summary>
\n\/\/\/ <param name="id"><\/param>
\n\/\/\/ <returns><\/returns>
\npublic string GetName(int id)
\n{
\n return string.Empty;
\n}
\n[\/csharp]<\/p>\n
\n\/\/\/ <summary>
\n\/\/\/ Gets the name.
\n\/\/\/ <\/summary>
\n\/\/\/ <param name="id">The id.<\/param>
\n\/\/\/ <returns><\/returns>
\npublic string GetName(int id)
\n{
\n return string.Empty;
\n}
\n[\/csharp]<\/p>\nAgent Smith<\/h3>\n
<\/a><\/a><\/a>