SlideShare a Scribd company logo
XML Documentation Comments
C# Programming Guide
Layout Conventions
 Good layout uses formatting to emphasize the
structure of your code and to make the code
easier to read. Microsoft examples and
samples conform to the following conventions:
 Use the default Code Editor settings (smart
indenting, four-character indents, tabs saved as
spaces). For more information, see Options, Text
Editor, C#, Formatting.
 Write only one statement per line.
 Write only one declaration per line.
 If continuation lines are not indented
automatically, indent them one tab stop (four
spaces).
 Add at least one blank line between method
definitions and property definitions.
 Use parentheses to make clauses in an
expression apparent, as shown in the following
code.
 See “Edit” menu -> Advanced ->
24.08.2016Roman Okolovich
Naming Guidelines
 The C# Language Specification does not define a
coding standard. However, the guidelines are used
by Microsoft to develop samples and documentation.
 Coding conventions serve the following purposes:
 They create a consistent look to the code, so that readers
can focus on content, not layout.
 They enable readers to understand the code more quickly
by making assumptions based on previous experience.
 They facilitate copying, changing, and maintaining the
code.
 They demonstrate C# best practices.
 C# Coding Conventions (C# Programming Guide)
 Naming Guidelines
24.08.2016Roman Okolovich
Naming Conventions
 General Naming Conventions
 Capitalization Conventions
 Naming Parameters
 Beyond the obvious reason of readability, it is important to
follow the guidelines for parameter names because
parameters are displayed in documentation and in the
designer when visual design tools provide Intellisense
and class browsing functionality.
 Names of Type Members
 Names of Classes, Structs, and Interfaces
 etc
24.08.2016Roman Okolovich
Names of Methods and Properties
 Names of Methods
 Because methods are the means of taking action, the design
guidelines require that method names be verbs or verb
phrases. Following this guideline also serves to distinguish
method names from property and type names, which are noun
or adjective phrases.
 ✓ DO give methods names that are verbs or verb phrases.
 Names of Properties
 Unlike other members, properties should be given noun phrase
or adjective names. That is because a property refers to data,
and the name of the property reflects that. PascalCasing is
always used for property names.
 ✓ DO name properties using a noun, noun phrase, or adjective.
 X DO NOT have properties that match the name of "Get"
methods
24.08.2016Roman Okolovich
Property Naming Guidelines
 Use a noun or noun phrase to name properties
 Use Pascal case
 Do not use Hungarian notation
 Consider creating a property with the same name as
its underlying type. For example, if you declare a
property named Color, the type of the property
should likewise be Color
public class SampleClass
{
public Color BackColor
{
// Code for Get and Set accessors goes here.
}
}
24.08.2016Roman Okolovich
Code Analysis Tool
 The code analysis tool in Visual Studio
examines your code for a set of common
defects and violations of good
programming practice. Code analysis
warnings differ from compiler errors and
warnings because the code analysis tool
searches for specific code patterns that
are valid but could still create issues for
you or other people who use your code.
 Code analysis can also find defects in
your code that are difficult to discover
through testing. Running the code
analysis tool at regular intervals during
your development process can enhance
the quality of your completed app.
24.08.2016Roman Okolovich
Comment fields
 In Visual C# you can create documentation for your code
by including XML elements in special comment fields
(indicated by triple slashes) in the source code directly
before the code block to which the comments refer, for
example:
namespace VNameSpace.Engine3D
{
/// <summary>
/// Message is broadcasted before Application is about to be destroyed
/// </summary>
public class ApplicationExitMessage
{
}
}
 When you compile with the /doc option, the compiler will
search for all XML tags in the source code and create an
XML documentation file. To create the final
documentation based on the compiler-generated file, you
can create a custom tool or use a tool such as
Sandcastle.
24.08.2016Roman Okolovich
Recommended Tags
 Documentation comments cannot be applied to a
namespace
 The compiler will process any tag that is valid XML.
 The following tags provide generally used
functionality in user documentation.
 For some tags the compiler verifies syntax
 Delimiters for Documentation Tags
 Example
24.08.2016Roman Okolovich
Links
 Framework Design Guidelines (.NET 4.5)
 C# Coding Conventions (C# Programming Guide)
 C# Coding Standards and Naming Conventions
(dofactory)
24.08.2016Roman Okolovich

More Related Content

PPTX
code analysis for c++
DOCX
Uniti classnotes
PPTX
Introduction of c programming unit-ii ppt
PPT
Abap course chapter 7 abap objects and bsp
PPTX
C Language (All Concept)
PDF
Learn C# programming - Program Structure & Basic Syntax
PDF
Assignment2
PPTX
C tokens
code analysis for c++
Uniti classnotes
Introduction of c programming unit-ii ppt
Abap course chapter 7 abap objects and bsp
C Language (All Concept)
Learn C# programming - Program Structure & Basic Syntax
Assignment2
C tokens

What's hot (20)

PDF
Book management system
PPTX
Introduction of C#
PPTX
C Token’s
PPTX
Complete Tokens in c/c++
PPT
Chapter2
PDF
Learn C# Programming - Decision Making & Loops
PDF
Learn C# Programming - Variables & Constants
DOC
PPTX
Introduction to c
PPT
Chap02
PPSX
Complete C programming Language Course
PPTX
C programming
PPTX
Application package
PPTX
Chapter3: fundamental programming
PPT
9781439035665 ppt ch04
PDF
Ooabap notes with_programs
PDF
Assignment5
PPTX
Basic c programming and explanation PPT1
PPTX
Unit 1 introduction to visual basic programming
PDF
C programming
Book management system
Introduction of C#
C Token’s
Complete Tokens in c/c++
Chapter2
Learn C# Programming - Decision Making & Loops
Learn C# Programming - Variables & Constants
Introduction to c
Chap02
Complete C programming Language Course
C programming
Application package
Chapter3: fundamental programming
9781439035665 ppt ch04
Ooabap notes with_programs
Assignment5
Basic c programming and explanation PPT1
Unit 1 introduction to visual basic programming
C programming
Ad

Similar to C# XML documentation (20)

DOCX
csharp.docx
PPT
Codingstandards matiar
PPTX
Back-2-Basics: .NET Coding Standards For The Real World
PPTX
Back-2-Basics: .NET Coding Standards For The Real World
DOCX
NamingConvention
PPT
Coding standard
PPTX
Coding standards
DOCX
PDF
Learn C# programming - Interfaces & Namespaces
PPTX
8-Roslyn for microsoft software framework.pptx
PPT
Html & CSS - Best practices 2-hour-workshop
PPT
Basics1
PPT
GTU PHP Project Training Guidelines
PDF
C 7 and NET Core Modern Cross Platform Development 2nd Edition Mark J. Price
DOCX
Assignment 3 Web Design Usability Guide PresentationBefore you .docx
PPTX
Cocoa and MVC in ios, iOS Training Ahmedbad , iOS classes Ahmedabad
PPTX
Writing High Quality Code in C#
PPTX
Web technologies-course 07.pptx
PPT
Automating C# Coding Standards using StyleCop and FxCop
TXT
csharp.docx
Codingstandards matiar
Back-2-Basics: .NET Coding Standards For The Real World
Back-2-Basics: .NET Coding Standards For The Real World
NamingConvention
Coding standard
Coding standards
Learn C# programming - Interfaces & Namespaces
8-Roslyn for microsoft software framework.pptx
Html & CSS - Best practices 2-hour-workshop
Basics1
GTU PHP Project Training Guidelines
C 7 and NET Core Modern Cross Platform Development 2nd Edition Mark J. Price
Assignment 3 Web Design Usability Guide PresentationBefore you .docx
Cocoa and MVC in ios, iOS Training Ahmedbad , iOS classes Ahmedabad
Writing High Quality Code in C#
Web technologies-course 07.pptx
Automating C# Coding Standards using StyleCop and FxCop
Ad

More from Roman Okolovich (10)

PPTX
Unit tests and TDD
PPT
Using QString effectively
PDF
Ram Disk
PDF
64 bits for developers
PDF
Virtual Functions
PDF
Visual Studio 2008 Overview
PDF
State Machine Framework
PDF
The Big Three
PDF
Parallel Programming
PDF
Smart Pointers
Unit tests and TDD
Using QString effectively
Ram Disk
64 bits for developers
Virtual Functions
Visual Studio 2008 Overview
State Machine Framework
The Big Three
Parallel Programming
Smart Pointers

Recently uploaded (20)

PDF
Design an Analysis of Algorithms I-SECS-1021-03
PDF
Why TechBuilder is the Future of Pickup and Delivery App Development (1).pdf
PPTX
Online Work Permit System for Fast Permit Processing
PDF
2025 Textile ERP Trends: SAP, Odoo & Oracle
PDF
PTS Company Brochure 2025 (1).pdf.......
PDF
Which alternative to Crystal Reports is best for small or large businesses.pdf
PPTX
ai tools demonstartion for schools and inter college
PDF
Nekopoi APK 2025 free lastest update
PPTX
CHAPTER 2 - PM Management and IT Context
PDF
How Creative Agencies Leverage Project Management Software.pdf
PDF
medical staffing services at VALiNTRY
PDF
SAP S4 Hana Brochure 3 (PTS SYSTEMS AND SOLUTIONS)
PDF
Wondershare Filmora 15 Crack With Activation Key [2025
PDF
Softaken Excel to vCard Converter Software.pdf
PDF
Adobe Illustrator 28.6 Crack My Vision of Vector Design
PDF
T3DD25 TYPO3 Content Blocks - Deep Dive by André Kraus
PDF
Design an Analysis of Algorithms II-SECS-1021-03
PDF
Claude Code: Everyone is a 10x Developer - A Comprehensive AI-Powered CLI Tool
PDF
Addressing The Cult of Project Management Tools-Why Disconnected Work is Hold...
PDF
How to Migrate SBCGlobal Email to Yahoo Easily
Design an Analysis of Algorithms I-SECS-1021-03
Why TechBuilder is the Future of Pickup and Delivery App Development (1).pdf
Online Work Permit System for Fast Permit Processing
2025 Textile ERP Trends: SAP, Odoo & Oracle
PTS Company Brochure 2025 (1).pdf.......
Which alternative to Crystal Reports is best for small or large businesses.pdf
ai tools demonstartion for schools and inter college
Nekopoi APK 2025 free lastest update
CHAPTER 2 - PM Management and IT Context
How Creative Agencies Leverage Project Management Software.pdf
medical staffing services at VALiNTRY
SAP S4 Hana Brochure 3 (PTS SYSTEMS AND SOLUTIONS)
Wondershare Filmora 15 Crack With Activation Key [2025
Softaken Excel to vCard Converter Software.pdf
Adobe Illustrator 28.6 Crack My Vision of Vector Design
T3DD25 TYPO3 Content Blocks - Deep Dive by André Kraus
Design an Analysis of Algorithms II-SECS-1021-03
Claude Code: Everyone is a 10x Developer - A Comprehensive AI-Powered CLI Tool
Addressing The Cult of Project Management Tools-Why Disconnected Work is Hold...
How to Migrate SBCGlobal Email to Yahoo Easily

C# XML documentation

  • 1. XML Documentation Comments C# Programming Guide
  • 2. Layout Conventions  Good layout uses formatting to emphasize the structure of your code and to make the code easier to read. Microsoft examples and samples conform to the following conventions:  Use the default Code Editor settings (smart indenting, four-character indents, tabs saved as spaces). For more information, see Options, Text Editor, C#, Formatting.  Write only one statement per line.  Write only one declaration per line.  If continuation lines are not indented automatically, indent them one tab stop (four spaces).  Add at least one blank line between method definitions and property definitions.  Use parentheses to make clauses in an expression apparent, as shown in the following code.  See “Edit” menu -> Advanced -> 24.08.2016Roman Okolovich
  • 3. Naming Guidelines  The C# Language Specification does not define a coding standard. However, the guidelines are used by Microsoft to develop samples and documentation.  Coding conventions serve the following purposes:  They create a consistent look to the code, so that readers can focus on content, not layout.  They enable readers to understand the code more quickly by making assumptions based on previous experience.  They facilitate copying, changing, and maintaining the code.  They demonstrate C# best practices.  C# Coding Conventions (C# Programming Guide)  Naming Guidelines 24.08.2016Roman Okolovich
  • 4. Naming Conventions  General Naming Conventions  Capitalization Conventions  Naming Parameters  Beyond the obvious reason of readability, it is important to follow the guidelines for parameter names because parameters are displayed in documentation and in the designer when visual design tools provide Intellisense and class browsing functionality.  Names of Type Members  Names of Classes, Structs, and Interfaces  etc 24.08.2016Roman Okolovich
  • 5. Names of Methods and Properties  Names of Methods  Because methods are the means of taking action, the design guidelines require that method names be verbs or verb phrases. Following this guideline also serves to distinguish method names from property and type names, which are noun or adjective phrases.  ✓ DO give methods names that are verbs or verb phrases.  Names of Properties  Unlike other members, properties should be given noun phrase or adjective names. That is because a property refers to data, and the name of the property reflects that. PascalCasing is always used for property names.  ✓ DO name properties using a noun, noun phrase, or adjective.  X DO NOT have properties that match the name of "Get" methods 24.08.2016Roman Okolovich
  • 6. Property Naming Guidelines  Use a noun or noun phrase to name properties  Use Pascal case  Do not use Hungarian notation  Consider creating a property with the same name as its underlying type. For example, if you declare a property named Color, the type of the property should likewise be Color public class SampleClass { public Color BackColor { // Code for Get and Set accessors goes here. } } 24.08.2016Roman Okolovich
  • 7. Code Analysis Tool  The code analysis tool in Visual Studio examines your code for a set of common defects and violations of good programming practice. Code analysis warnings differ from compiler errors and warnings because the code analysis tool searches for specific code patterns that are valid but could still create issues for you or other people who use your code.  Code analysis can also find defects in your code that are difficult to discover through testing. Running the code analysis tool at regular intervals during your development process can enhance the quality of your completed app. 24.08.2016Roman Okolovich
  • 8. Comment fields  In Visual C# you can create documentation for your code by including XML elements in special comment fields (indicated by triple slashes) in the source code directly before the code block to which the comments refer, for example: namespace VNameSpace.Engine3D { /// <summary> /// Message is broadcasted before Application is about to be destroyed /// </summary> public class ApplicationExitMessage { } }  When you compile with the /doc option, the compiler will search for all XML tags in the source code and create an XML documentation file. To create the final documentation based on the compiler-generated file, you can create a custom tool or use a tool such as Sandcastle. 24.08.2016Roman Okolovich
  • 9. Recommended Tags  Documentation comments cannot be applied to a namespace  The compiler will process any tag that is valid XML.  The following tags provide generally used functionality in user documentation.  For some tags the compiler verifies syntax  Delimiters for Documentation Tags  Example 24.08.2016Roman Okolovich
  • 10. Links  Framework Design Guidelines (.NET 4.5)  C# Coding Conventions (C# Programming Guide)  C# Coding Standards and Naming Conventions (dofactory) 24.08.2016Roman Okolovich