Keep your C# XML comments to yourself!
- Category: Software Development
- Posted On: 9/22/2006
- Views: 8,032
You have probably heard the phrase "keep your comments to yourself" before. When I first learned about C# XML comments, I quickly adopted it as a standard for much of my code (even non-.NET). This was further enforced when NDoc was released to compile my comments into pages and pages of pretty web pages or a Microsoft compiled help file. Yes, I saw the future and used the tags as a personal standard in everything I did... NDoc changed my world of code documentation to something like "write your comments down and publicize them to everyone that may ever benefit from your unique insight." (everyone you trust and have approval to share the info with of course) [Thank sue-happy America and lawyers for that one...]
Somewhere along the way, I stopped using the XML comments for anything other than exposed properties and methods. I kept commenting the private stuff, but I used standard comment syntax without the XML mark-up. I guess my brain subconsciously determined that if NDoc didn't care about them, why should I? I mean, developers are only going to be dealing with the protected and public pieces that my code provides, right?
WRONG! Two words... code maintenance. If I have to interface with your class, it's awesome to simply scan an up-to-date NDoc-generated help file. But, what if I have to edit a class you originally wrote? Especially when you're not around... Yes, I could browse to the code in question and read your standard comments. But, how great would it be to be looking at something that calls a private method in your class and see a summary when you put your mouse over the method or property in question? I simply overlooked this benefit for a couple of years. Intellisense and tooltips in Visual Studio ALWAYS use the XML code comments to provide a summary when they are available. Yes, the person could use shortcuts to skip right to a method and back again. But, why not just document everything using the same approach? Inline comments within a routine are the exception. The person has to be there, looking at the code, so the comments can simply sit there as-is.
So, remember to share your code comments and don't just keep them to yourself.
- Category: Software Development
- Posted On: 9/22/2006
- Views: 8,032