Question

I'm building application and one of requirements is to use a comments like this one:

/// <summary>
/// Creates new client.
/// </summary>
/// <param name="uri">The URI.</param>
/// <param name="param">The param.</param>
/// <returns></returns>

I understand that it's easy for various kind of tools to generate the docs based on these xmls. But it significantly decreases code readability, and that's exactly what we, humans, trying to achieve.

Could this approach be replaced by any other technique in .Net? And what's the better way to improve code readability and cleanness?

No correct solution

OTHER TIPS

That information should pop up on visual studio when someone uses intellisense while going through your methods. This will save time since whoever is using your code will not need to go into your code (thus meaning that you also do not need to expose any of your code) and see what other comments you have written.

I think that documentation, when is kept short and to the point, is never a bad thing and it does not affect code readability.

While using a third party dll does intellisense hurt you?

I don't think it does. And this is one of the major reasons of using this commenting.

Let's say you are righting a dll (or writing a class that somebody else will use), won't it be helpful to him/her that as he types he knows what the method does and what is working of parameters?

You should absolutely not avoid these comments! They provide IntelliSense for Visual Studio, and can form the basis of automatic documentation Tools such as SandCastle. To my knowledge Your only option in terms of techniques is this one (to get all these features).

To help with readability you can minimize each comment with the [-] next to the first tag in Visual Studio. That way you will only see the first line. This can be helpful when working on the code day-to-day.

I also find the navigation dropdown lists helpful to locate methods within a class, if you find the xml to make it more difficult to navigate / browse.

But using them is a good thing and you get used to having them around

Different documentation formats are suited for different scenarios.

XML comments are best suited for automatic help file generation and Intellisense. By necessity, they are more verbose than other methods as they require specific tags to be present in order to generate the documentation. While the syntax could be better, remember they were created way back when everyone thought XML was a cool idea.

For general commenting, you can use a literate programming style and tools like nocco to create and display HTML pages. The tool extracts the comments and displays them in an HTML page alongside the code. The nocco page itself is the output of nocco on nocco.cs

Nocco even uses Markdown for formatting.

Of course, you can mix and match methods, eg. use XML comments for public methods, literate comments for internal comments.

the VS documentation and comment do not decrease code readability for most people, it's the other way around. if you feel that these comments make the code less readable you can collapse them or even change the color they are drawn.

but think of how helpful it is when you put the cursor above a function and the information of the method and it's parameters appears. That's readability at it's best

Licensed under: CC-BY-SA with attribution
Not affiliated with StackOverflow
scroll top