XML Comments in C#

You want to know when to use XML comments in C#.

Use XML comments to document all public types and their public members in an API (e.g. class libraries). Use standard class and method-level comments for types and methods that aren’t visible from outside the project.

XML comments have two great advantages. First, XML documentation can easily be generated by enabling an option on the Build screen of the Project Properties tab. Second is that NDoc can then be used to produce technical documentation for the API. The downsides of XML comments is they take up screen real estate and make comments less readable. However, you can collapse them and display them only when necessary. In addition, it may be advantageous to enable the XML Documentation File option only in release mode. Doing so will prevent slowing down the compilation process during debug and test phases.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s