6

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?

Roman Pushkin
  • 5,639
  • 3
  • 40
  • 58
  • 3
    "what's the better way to improve code readability and cleanness" writing code which is selfexplaining and not using many comments – Kamil Budziewski Aug 20 '13 at 07:03
  • 1
    In what way does it decrease code readability? It exists outside of the methods themselves. – Damien_The_Unbeliever Aug 20 '13 at 07:04
  • 3
    Also this can be collapsed in VisualStudio – Tobia Zambon Aug 20 '13 at 07:04
  • Your `` and two `` are indeed entirely value-less (due to the contents not entered) and should be removed; the `` is definitely useful, but could perhaps use more attention. – Marc Gravell Aug 20 '13 at 07:08
  • 6
    @wudzik: There's a massive difference between an *implementation* which is clear and doesn't require comments, and not bothering to document your public API. – Jon Skeet Aug 20 '13 at 07:08
  • If this is an api, you should comment it. But for everything else, the comment doesn't add much, maybe pick a better name for "param". – Carra Aug 20 '13 at 07:13
  • There are alternatives, like nocco and other literate programming tools – Panagiotis Kanavos Aug 20 '13 at 07:18
  • @JonSkeet of course there's massive difference, I said only that code has to be selfexplaining. I don't say that you don't need to write documentation :) look at the quoute before my words. – Kamil Budziewski Aug 20 '13 at 07:49
  • 2
    @wudzik: But given that this question is *about* documentation (rather than implementation), I don't see how your comment is relevant. – Jon Skeet Aug 20 '13 at 08:01
  • Whoever thought this is an opinion-based question probably doesn't know about the documentation tools available for .NET outside Visual Studio ... – Panagiotis Kanavos Aug 21 '13 at 12:37

5 Answers5

7

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.

npinti
  • 51,780
  • 5
  • 72
  • 96
  • Yep, sure, I understand that. But at the same time a lot of tools automatically pastes all of these xml comments for you (GhostDoc). In some companies they don't even bother to write more. It's OK for them to have these auto-generated comments. Anyway, I was expecting that the answer will be like to use a tool to hide xml comments, or organize them in a better way. – Roman Pushkin Aug 20 '13 at 07:27
  • 1
    @RomanPushkin: You can take a look at this link: http://stackoverflow.com/questions/8696586/c-sharp-hide-and-unhide-comments maybe there is some information which you might be after. – npinti Aug 20 '13 at 07:45
  • XML comments are not the only way to generate documentation for .NET projects, and they ARE ugly. They are suitable for Intellisense or API help file generation, but don't cover at all scenarios like documentation of the code itself, just the exposed API. Tools like nocco address the latter scenario – Panagiotis Kanavos Aug 21 '13 at 12:41
2

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?

Ehsan
  • 31,833
  • 6
  • 56
  • 65
1

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

havardhu
  • 3,576
  • 2
  • 30
  • 42
1

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.

Panagiotis Kanavos
  • 120,703
  • 13
  • 188
  • 236
0

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

No Idea For Name
  • 11,411
  • 10
  • 42
  • 70