Skip to content

BRO1134: Declarations should not contain embedded comments

A comment between the header of a type, namespace, member, accessor or local function and its { moves into the body. BRO1132 (StyleCop's SA1108) does the same for statements. Not a StyleCop rule: proposed in StyleCop's issue #605, which the maintainers favored and nobody built.

Example

Before

public class Cache
// keeps one item
{
    private object item;

    public object Get()
    // loads on first use
    {
        return item ??= new object();
    }

    public int Count
    // 0 or 1
    {
        get
        {
            return item == null ? 0 : 1;
        }
    }
}

After

public class Cache
{
    // keeps one item
    private object item;

    public object Get()
    {
        // loads on first use
        return item ??= new object();
    }

    public int Count
    {
        // 0 or 1
        get
        {
            return item == null ? 0 : 1;
        }
    }
}

Why

A comment on its own line between a declaration's header and { splits the declaration in two. At the top of the body it reads as a note about the type or member, next to the code it describes. A note that documents the member for its callers belongs in a /// comment above it instead.

How the fix works

Like BRO1132's: each comment goes on its own line right after { (below blank lines there, which are BRO1503's), indented like the body's first line (one level deeper than { in an empty body), in its original order. A line that held only the comment is removed. BRO1504 doesn't ask for a blank line above a comment this rule moves.

Checked: classes, structs, interfaces, records and enums with a body; block-scoped namespaces; methods, constructors, finalizers, operators and conversion operators with a block body; the accessor list of a property, indexer or event; an accessor's block body; local functions with a block body. Both // and /* */ comments count, on a line of their own before {, or after the header when { follows on the same line.

Not reported

  • A comment that ends the header's line, with { on the next line (public int GetHashCollissions() // legacy spelling): a note on the header, which often explains the name or a parameter rather than the body (the owner's decision, see decisions). A comment on a line of its own below it still moves.
  • //// comments (commented-out code).
  • A comment after {, inside the header (between parameters), or above the declaration, and a comment after an attribute on its own line ([Fact] // flaky).
  • A header spanning several lines (parameters, a base list or constraints on further lines), like BRO1132: the comment usually explains the last line, not the body.
  • A body on one line with its { (void M() // note + { }): there's no line inside it for the comment.
  • A comment spanning lines or a directive between the header and {.
  • Expression bodies (=> ...), file-scoped namespaces and declarations without a body: there's no {.

Compared with StyleCop

StyleCop has no such rule: SA1108 checks statements only. Issue #605 proposed it for declarations and accessors. stylebro-migrate turns this rule off, so migrating doesn't change a StyleCop-clean repository.