Why should I use these nasty comments in C # /. Net code?

Question

I am creating an application, and one of the requirements is to use comments like this:

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

I understand that for various types of tools it is easy to create documents based on these xmls. But this greatly reduces the readability of the code, and exactly what we humans are trying to achieve.

Is it possible to replace this approach with any other technique in .Net? And what is the best way to improve readability and cleanliness of the code?

Answer 1

This information should appear in the visual studio when someone uses intellisense when viewing your methods. This will save time, since the one who uses your code will not necessarily enter your code (which means that you also do not need to expose any of your code) and see what other comments you wrote.

I think that documentation, when it remains short and accurate, is never bad and does not affect the readability of the code.

Answer 2

Does using a third-party dll intellisense harm you?

I do not think so. And this is one of the main reasons for using this comment.

Let's say you fix the dll (or write a class that someone else will use), will it be useful for him / her, that when he types, he knows what this method does and what works with parameters?

Answer 3

You absolutely do not avoid these comments! They provide IntelliSense for Visual Studio and can form the basis of automated documentation tools such as SandCastle. As far as I know, your only option from a technical point of view is one (to get all these features).

To make reading easier, you can minimize each comment by using the [-] next to the first tag in Visual Studio. Thus, you will see only the first line. This can be useful for daily work on code.

I also found that navigation drop-down lists are useful for finding methods within a class if you find that xml makes navigation / browsing difficult.

But using them is good, and you get used to surround them

Answer 4

Different documentation formats are suitable for different scenarios.

XML comments are best suited for automatically creating help files and Intellisense. If necessary, they are more detailed than other methods, since they require certain tags to create documentation. Although the syntax might be better, remember that they were created back when everyone thought XML was a cool idea.

For general commenting, you can use a competent programming style and tools like nocco to create and display HTML pages. The tool extracts comments and displays them on an HTML page along with code. The nocco page itself is nocco's output on nocco.cs

Nocco even uses Markdown for formatting.

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

Answer 5

VS documentation and comment do not reduce the readability of the code for most people, it is the other way around. if you think these comments make the code less readable, you can roll them up or even change the color they painted.

but think how useful this is when you place the cursor over a function, and information about the method and its parameters appears. This readability is best.