Centric connect.engage.succeed

XML Doc Comments, not only for API Developers!

Geschreven door Arnoud van Bokkem - 30 november 2017

Arnoud van Bokkem
Put a bunch of developers together in a team and invariably there will be discussion about code comment. Two sides will emerge, one preaching the joy of code comments, the other side vehemently opposed to these. But who is in the right?

Of course, the truth can be found somewhere in between. I recently read a blog by Michael Sorens about nine categories of comments he distinguishes, from just repeating the code in different words (100% evil) to explaining the why of the code (100% good), with all kinds of less extreme good or bad practices in between. I very much agree with the distinction he makes between different types of comments and whether each particular type is evil or not. I recommend you give his blog a read: https://www.red-gate.com/simple-talk/opinion/opinion-pieces/fighting-evil-code-comments-comments/

API doc comments

I would like to talk some more about one of the categories Michael distinguishes: API doc comments. Mind you, this category is not only about creating a library with a published API for other developers to buy and use. This type of comment is relevant to all classes and their exposed members; it’s about writing documentation comments for all public or protected classes and public or protected members. Why? Because, at some point, someone will be consuming these classes. And he or she will want to know how to use your code, without having to redo the whole analysis you did to create the class in the first place. This even holds true when the person using your code is you (or do you always remember why you wrote that class a year ago?).

Using documentation comments

So, you want to use documentation comments in your code. In C#, the format used for documentation comments is called XML Documentation Comments:

XML Doc comment

Adding an XML Documentation Comment to a C# class or a method is easy in Visual Studio: just type three slashes where you want the comment to appear and start typing some meaningful text:

Add comment by entering three slashes

If the method contains any parameters, they are added automatically, as is the case in the example above. Make sure you write some meaningful text for the parameters as well, so the developer who uses this method will know what value is expected for the parameter. Visual Studio is aware of the XML Documentation Comments that are added to the code and will show them in IntelliSense:

Show code comments in IntelliSense

As well as summary and param, you can add other XML documentation tags to the XML Documentation Comment section, like returns, remarks, example and exception. See https://docs.microsoft.com/en-us/dotnet/csharp/codedoc for a walkthrough and recommendations.

In my opinion, some tags, though very useful for API documentation, might be a bit too much for use within a team. For instance, I almost never use the tag example. If a colleague wants to see how your class should be used, he or she can simply find all references for the item to see real life examples of your code at work. But in the end, it’s all about getting your colleagues to use your code correctly. So, if you think an example might be useful, by all means add it. If you are writing API documentation, I would definitely add examples of how to use the API. Take the .NET Framework documentation on MSDN, for instance: I almost always scroll down to the examples to really understand what I should do.

If you consistently write XML Documentation Comments for each exposed class and method, you will help the developer who uses your class; he or she does not have to look into the code of your class, but can rely on IntelliSense to know what’s going on.

Side note: JavaScript

On a side note, documentation comments also exist for JavaScript. Although different in syntax, the idea is the same. If a comment starts with a slash, followed by two asterisks, it is considered API documentation. Out of the box, Visual Studio does not support creating a documentation comment in JavaScript; it only supports showing the comments in IntelliSense. There are, however, extensions like DocStubsJs2017 that do support this behaviour. ReSharper has support for adding documentation comments too:

Add JavaScript comment by entering slash asterisk asterisk

What are good documentation comments

Now that we’ve dealt with the technical part of writing document comments, it’s time to discuss the contents of the comment tags. As Michael points out in his blog, you should not just repeat the name in different words: you should explain what it does and why. For instance, a Boolean parameter with a name useAlternativeSaveMode could have a description: “True if the method should use the alternative save mode, false otherwise”, but that does not mean anything unless the description also explains what that alternative save mode means – and even better, why you should use the alternative save mode.

It’s important to note that you are writing your comments for someone else, someone who might not be as experienced as you are. Put yourself in this person’s shoes for a moment and think about what he or she might want to know about your method.

In my experience, spending some time thinking about what a method does or what a parameter should contain not only helps you write better comments: it may even help you come up with a better name for the method or the parameter itself. On occasion, I have even changed the contents of a method after thinking about what the code should do and realising that the current implementation differed from that.

Conclusion

Some types of comments are good, some are evil. XML Documentation Comments are a valuable tool to help team members use and understand your code. Therefore, they fall under good comments, provided you write meaningful content inside the tags.

About Arnoud

Craft Expert Arnoud van Bokkem is part of the .NET team within Craft, the development programme for IT professionals (powered by Centric). If you would like to follow his blog, sign up for Craft updates.

Tags:.NET

     
Reacties
  • Simone
    23 december 2017
    Als iemand die geen fan is van commentaar in code werd ik aangetrokken door de titel van dit stuk. Maar na het lezen moet ik helaas zeggen dat je me niet overtuigd hebt. Dat komt vooral door de voorbeelden die je gebruikt.
    Je geeft zelf aan dat "just repeating the code in different words" slecht commentaar is, maar dat zie ik nu precies terug in je voorbeelden.
    Het zegt niet meer dan dat ik al aan de naam kan zien.
    En het voorbeeld dat je aan het eind aanhaalt, een methode met een boolean parameter. Je zou hier geen commentaar bij nodig hebben, je zou geen boolean parameter moeten gebruiken. Die geeft aan dat de methode op 2 manieren gebruikt kan worden, schrijf clean code en maak er 2 methodes van met een duidelijke naam en dan is uitleg niet nodig.
  • https://babasupport.org/dell/dell-error-code-2000-0142/
    Dell error code 2000-0142
    31 oktober 2018
    By the post, we can understand that the XML doc documentation is really not only for the API developers but it can also be accessible to the different aspects also.
Schrijf een reactie
  • Captcha image
  • Verzenden