Metadata

ID: csharp-best-practices/summary-documentation-comment

Language: C#

Severity: Info

Category: Best Practices

Description

The rule requires that all classes and methods in C# have a summary documentation comment. The summary documentation comment is a special type of comment that starts with /// <summary> and ends with /// </summary>. This comment is used to provide a brief description of the class or method, which can be helpful for other developers, or for generating documentation.

The lack of summary documentation can make the code harder to understand and maintain, especially for large projects or when working in a team. It can be difficult to understand the purpose of a class or method just by its name, especially if it’s complex or not self-explanatory. Providing a summary documentation comment can save time and effort for anyone who needs to understand or update the code in the future.

How to remediate

Ensure that the documentation comments (starting with ///) have the <summary></summary> field.

Non-Compliant Code Examples

/// a class doing something
/// a lot of things!
public class MyClass()
{
    /// a method doing something
    public void foo() {

    }
}

Compliant Code Examples

// a class doing something
// a lot of things!
public class MyClass()
{
    // a method doing something
    public void foo() {

    }
}

/// <summary>
///
/// </summary>
public class MyClass()
{
    /// <summary>
    ///
    /// </summary>
    public void foo() {

    }
}

Seamless integrations. Try Datadog Code Security

Datadog Code Security