3

Lately I started using /// to comment my C# code rather than // or /* because it is just much simpler to use. Today I started wondering why there were different types and came across this SO question which states that /// comments are for generating the xml documentation.

I can't find any advice with regards to on type of comments vs another on Google and I take that to mean that it doesn't matter either way. I'm not getting any ill effects so far from using /// to comment, but I'd hate to get into a habit now just to unlearn it later. As far as I can tell, if there are no metatags in the comments it does not get recognised as being documentation (or am I completely wrong on that?)

Before I riddle my code with /// comments, is this type of commenting a big no-no? Could there be potential problems from commenting this way?

Community
  • 1
  • 1
yu_ominae
  • 2,975
  • 6
  • 39
  • 76
  • three slashes are used for describing the declared method or function. I know that much only. – Mr_Green Nov 14 '12 at 06:16
  • I actually just answered a question explaining the differences today. http://stackoverflow.com/questions/13366400/should-you-use-xml-comments-on-field-variables-properties-constructors/13366665#13366665 – evanmcdonnal Nov 14 '12 at 06:16
  • What makes you think that documentation of code is no-no? – Euphoric Nov 14 '12 at 06:16
  • use triple slashes for what they were intended for; which is not standard comments. Also: if you find you are putting many comments into code, perhaps you should try to make the code more self documenting.... – Mitch Wheat Nov 14 '12 at 06:21
  • 1
    Here is standard c sharp coding convention document. It will be helpful for you. http://se.inf.ethz.ch/old/teaching/ss2007/251-0290-00/project/CSharpCodingStandards.pdf – Đức Bùi Nov 14 '12 at 06:23
  • @Mitch Wheat: I always hope that my code is self-documenting if I make meaningful variable and method names, but I like to talk myself through blocks of code in case I get back to them later... Is there any way to make a code more self-documenting? – yu_ominae Nov 14 '12 at 06:26

3 Answers3

6

Could there be potential problems from commenting this way?

Yes. When you decide to generate your project documentation, then it will have all those commented lines as part of your XML documentation. When you compile the code using /Doc extension then it generates a document using your XML comments (///). If you have used that to comment out your code, then the document generate will consider the commented out code for your documentation.

Please see:

XML Documentation Comments (C# Programming Guide)

How to: Generate XML Documentation for a Project

Habib
  • 219,104
  • 29
  • 407
  • 436
  • @slugster, thanks, I added that to my answer with your reference – Habib Nov 14 '12 at 06:28
  • Wow, good points. I never had to generate documentation before and didn't know about `TODO` and other keywords. Back to `//` commenting it is then. I wish it would automatically do line breaks though... – yu_ominae Nov 14 '12 at 06:31
  • @user643192, not sure about the line breaks, but I use shortcut for commenting. Select Text and press `Cntl+K,C` and `Cntl+K,U` for uncomment – Habib Nov 14 '12 at 06:32
  • Thanks for the shortcut, but I have found that writing ext first and commenting later doesn't work too well because of intellisense, so I always put the comment slashes in first. – yu_ominae Nov 14 '12 at 06:34
  • @Habib My apologies, I got it wrong - `HACK` and `TODO` **will** show up in the task list when using three slashes - I just did a quick check in VS2010 and it works (it must have been an earlier version where it didn't). – slugster Nov 14 '12 at 12:49
  • @slugster, glad you checked it, I was about to do it as well. but great it would show up. I am going to edit my answer – Habib Nov 14 '12 at 12:59
  • 1
    Also have a look at [Sandcastle Help File Builder](http://shfb.codeplex.com/). Sandcastle uses the XML documents created by your doc-comments in order to automatically create a code documentation as help file. – Olivier Jacot-Descombes Nov 14 '12 at 13:29
1

There isn't any technical difference as far as code compilation goes. They're all ignored.

I believe the /// comment is more of a convention to signify that you are commenting a particular code block with XML Documentation Comments. IDEs like Visual Studio are geared to recognise the different comment type and will visually style accordingly.

Given that is general convention to use standard // or /* */ comments, there's also the potential to confuse (or, more likely, annoy) other developers who will read your code.

Nigel Whatling
  • 2,371
  • 1
  • 16
  • 22
0

If you use delvelopment help tools like resharper for example mostly they offer you such a functionalities of commenting acode block either with // or with /* ... */, these commented code blocks can be toggeled using these tools, this wouldnt work for you once you have 3 slashes instead of 2.

The issue with the documentation symbols is another one, you will get comments generated in your documentation without having the control on what stayes a acomment in code and what gets into the documetnation since you have all over ///, but i guess this is an issue one can configure inthe documentation generation tool.

CloudyMarble
  • 36,908
  • 70
  • 97
  • 130
  • Actually it is less work to use `///` because it automatically comments the new line after a return. `//` have to be added manually on every line. – yu_ominae Nov 14 '12 at 06:29