155

I realized today that I don't know how to escape characters in comments for C#. I want to document a generic C# class, but I cannot write a proper example since I don't know how to escape the < and > characters. Do I have to use &lt; and &gt;? I don't like if that is the case since I want to make it easy to read the comment in the actual document so I don't have to generate some kind of code document to be able to read the example code.

Improve this question
4
  • 1
    Could you show an example comment?
    – BoltClock
    Commented Dec 7, 2010 at 13:59
  • possible duplicate of Xml string in a C# summary comment
    – Mark Pim
    Commented Dec 7, 2010 at 14:04
  • 1
    @Mark: You're right, but it's not only XML... I was trying to write an example for generics which is not XML but it uses '<' and '>'. But the solution is the same for both.
    – Tomas Jansson
    Commented Dec 7, 2010 at 15:45
  • The greater-than symbol doesn't need to be escaped, and for the less-than symbol you can paste this slight variation: ⋖
    – Digiproc
    Commented Jul 3, 2023 at 8:57

8 Answers 8

Reset to default
189

If you need to escape characters in XML comments, you need to use the character entities, so < would need to be escaped as &lt;, as in your question.

The alternative to escaping is using CDATA sections, to the same effect.

As you noted, this would produce good looking documentation, but a horrible comment to read...

Improve this answer
4
  • 31
    Just for reference < would be &lt; and > would be &gt;. As an example, List&lt;string&gt; myStringList = new List&lt;string&gt;();
    – Arvo Bowen
    Commented Jun 7, 2016 at 0:00
  • 2
    @ArvoBowen Just in case someone's missing the obvious, lt/gt stand for “less than”/“greater than”, respectively.
    – Lukas Juhrich
    Commented Jul 12, 2019 at 7:58
  • 1
    Interestingly, only < needs to get escaped with &lt;, > can stay as it is: List&lt;string> myStringList = new List&lt;string>();. At least this works in intellisense. Strangely enough, CDATA does not work in intellisense. I didn't check how it looks in auto-generated docs.
    – Peter Huber
    Commented Mar 29, 2020 at 4:11
  • Can confirm that VS 2013 does not render CDATA in intellisense. &lt; makes the comment hard to read.
    – Alex
    Commented Jul 29, 2020 at 0:25
74

In plain C# comments you can use any character (except */ if you started the comment with /*, or the newline character if you started the comment with //). If you are using XML comments then you can use a CDATA section to include '<' and '>' characters.

See this MSDN blog article for more information on XML comments in C#.

For example

/// <summary>
/// Here is how to use the class: <![CDATA[ <test>Data</test> ]]>
/// </summary>
Improve this answer
3
  • 16
    You're probably correct if you want to genereate nice looking html-documents, but I'm more interesting about getting the intellisense tips in VS correct, and for that it seems that I have to use XML escaping. But +1 for the alternative.
    – Tomas Jansson
    Commented Dec 7, 2010 at 15:43
  • 3
    Hmm, illegible machine garbage in my comments only help if we take the time to build our document file when the vast, vast, vast (did I mention vast?) majority of use cases is reading the comments in the source (preferably an interface).
    – Rick O'Shea
    Commented Oct 21, 2018 at 18:19
  • In VS2022, using CDATA in the XML comments highlights them in a different color and makes them very readable. A great way to include a code sample in the comment. Meanwhile intellisense strips the CDATA markup and shows the raw content. For example if my comment was "Use it like this: <![CDATA[ MyType<T> t = new MyType<T>(); ]]>" then it looks like this in intellisense: "Use it like this: MyType<T> t = new MyType<T>();
    – Steve Lautenschlager
    Commented Dec 16, 2022 at 18:19
24

You said "I want to make it easy to read the comment in the actual document". I agree.

Developers spend most of their lives in the code, not perusing auto-generated docs. Those are great for thirdparty libraries like charting, but not for in-house development where we work with all of the code. I'm sort of shocked that MSFT hasn't come up with a solution that supports developers better here. We have regions that dynamically expand/collapse code...why can't we have an in-place comment rendering toggle (between raw text and processed XML comment or between raw text and processed HTML comment)?. Seems like I should have some elementary HTML capabilities in my method/class prologue comments (red text, italics, etc). Surely an IDE could work a little HTML processing magic to liven up inline comments.

My hack-of-a-solution solution: I change '<' to "{" and '>" to "}". That seems to cover me for the typical example usage style comment, including your specific example. Imperfect, but pragmatic given the readability issue (and problems with IDE comment coloring that ensue when using '<')

Improve this answer
2
  • 6
    Your "hack of a solution" seems to be more correct than you think. According to this the compiler recognizer curly braces as angle brackets and binds them correctly.
    – RubberDuck
    Commented Jan 16, 2015 at 1:18
  • I agree. C# is severely lacking in the documentation area, which is sad because (bias incoming) Java does it really well, and Java should not be doing anything better than C#! JavaDoc allows for HTML tags such as italics, bold, lists (yes I know C# docs can have lists but they're fugly in IntelliSense), hyperlinks, links to code within the project, images, and you can even use font style CSS to colour the text! I would much prefer to see the documentation in an easily-readable format in the IDE, rather than chasing it up online. It's a time-saver to be sure. MSFT need to up their game here!
    – Logix
    Commented Sep 30, 2020 at 15:50
12

C# XML comments are written in XML, so you would use normal XML escaping.

For example...

<summary>Here is an escaped &lt;token&gt;</summary>
Improve this answer
1
  • I forgot the ";"
    – msteel9999
    Commented Nov 2, 2021 at 9:59
5

I've found a livable solution to this problem is simply including two examples: one difficult-to-read version in the XML comments w/ escape characters, and another readable version using conventional // comments.

Simple, but effective.

Improve this answer
3

Better than using {...} is using ≤...≥ (less than or equals sign, greater than or equals sign, U2264 and U2265 in Unicode). Looks like underlined angle brackets but still definitely angle brackets! And only adds a couple of bytes to your code file.

Improve this answer
2

I like @Mick Bruno's idea of using similar looking characters to keep it legible in the code. Single guillemets work pretty well:

List‹int›

The Windows keyboard shortcuts are:

  • Alt+0139
  • Alt+0155

(where the numbers are typed on the keypad)

Improve this answer
3
  • 1
    Readable in code file and in intellisense.
    – Steve Lautenschlager
    Commented May 31, 2023 at 16:29
  • This will be infuriating if anyone tries to copy-paste the example you give in documentation with "fake" <>
    – beyarkay
    Commented Jul 3 at 6:46
  • 1
    @beyarkay, fair point, but I never use it for example code, just for referencing generic classes
    – Giles
    Commented Jul 8 at 15:11
0

Even better try U2280 and U2281 - just copy and paste from List of Unicode characters (mathematical operators section).

Improve this answer
3
  • 1
    Unicode operators are OK when they are used to represent actual mathematical operators, poor if they are used in code snippets that happen to be in a comment (e.g. List<int>). Think about e.g. copy-pasting the code snippet.
    – Palec
    Commented Jan 30, 2017 at 11:41
  • can you provide an example of how using this in a comment ? never used unicode characters indeed
    – ClementWalter
    Commented Apr 20, 2017 at 9:44
  • 1
    Copy and paste the character as described above.
    – Paul Coulson
    Commented Apr 21, 2017 at 12:57

Not the answer you're looking for? Browse other questions tagged or ask your own question.