Skip to content

Comments.md

Latest commit

 

History

History
87 lines (67 loc) · 2.74 KB

Comments.md

File metadata and controls

87 lines (67 loc) · 2.74 KB

Comments

DO

  • use the english language
  • write full sentences beginning capitalized and ending with a period
  • be precise
  • use documentation comments (///) where applicable
  • write comments in separate lines above the code they comment
  • use a space between comment delimiters (//, /*, *) and the comment

DO NOT

  • use comments to remove parts of code
  • leave outdated comments in the code

Documentation comments

Documentation comments are formatted using XML tags. These are processed by the compiler, they can be exported into documentation files and shown in IntelliSense.

Documentation comments can be used on nearly everything except namespaces.

  • The summary tag should only display the most important information
  • Use remarksto add additional information to the documentation
  • The comments rules from above apply as well

Types

  • Every type should have at least the summarydocumentation
  • summary should begin with the keywords Representsor Provides
/// <summary>
/// Represents a mesh.
/// </summary>
public class Mesh { }

/// <summary>
/// Provides user input
/// </summary>
public class Input  { }

Methods

  • A method should atleast be documented with a summary tag
  • Method summary always begins with a verb
  • 'summary' documents what is done, not how

Parameters

  • If there are method parameter they should be documented with param
  • bool parameter descriptions begin with Specifies wether
  • enum parameters should be documented with Specifies ...

Returns

  • A return value should be documented using the returns tag
  • In case of bool returns the description should follow the concept of true if condition; else false

Exceptions

  • An exception that needs catching should be documented
  • Use the exception tag with a reference to the type of an exception and state the reason why an exception occurred
/// <summary>
/// Writes the mesh to a file.
/// </summary>
/// <param name="path">The file system path</param>
/// <param name="overwriteExisting">Specifies whether an existing file will be overwritten</param>
/// <exception cref="ArgumentNullException"><paramref name="path"/> is <see langword="null" />.</exception>
public void WriteMeshToFile(string path, bool overwriteExisting)
{
    ...    
}

Properties

  • summary documentation starts with Gets, Sets or Gets or sets depending on whether it is read-only, write-only or fully accessible
/// <summary>
/// Gets or sets the vertices.
/// </summary>
public Vertex[] Vertices { get; set; }

Resources