BRO1504: Single-line comments should be preceded by a blank line¶

A // comment that follows code on the line above gets a blank line before it. Replaces StyleCop SA1515.

Example¶

Before¶

public class Totals
{
    public decimal Sum(decimal[] amounts)
    {
        var sum = 0m;
        // Round each amount first, like the invoice does.
        foreach (var amount in amounts)
        {
            sum += decimal.Round(amount, 2);
        }
        // The caller adds VAT.
        return sum;
    }
}

After¶

public class Totals
{
    public decimal Sum(decimal[] amounts)
    {
        var sum = 0m;

        // Round each amount first, like the invoice does.
        foreach (var amount in amounts)
        {
            sum += decimal.Round(amount, 2);
        }

        // The caller adds VAT.
        return sum;
    }
}

Why¶

A comment usually introduces the code below it. A blank line above makes clear which code it belongs to, and splits a long method into readable steps.

How the fix works¶

The fix inserts a blank line above the comment.

Configuration¶

# Comments whose text starts with one of these (comma-separated, case-sensitive) need no blank line above.
# Default: none.
stylebro_comment_blank_line_exempt_prefixes = ReSharper, @formatter

Tool markers such as // ReSharper disable once UnusedVariable or // @formatter:off belong to the line below them and aren't the start of a new step, so a blank line above them only pushes them away from the code they mark (StyleCop issues #3546 and #1490, where the only workaround is ////). The prefix is matched against the comment's text after // and any spaces, so ReSharper covers // ReSharper disable and //ReSharper restore.

Not reported¶

Like StyleCop:

The line above is blank, another comment, or a preprocessor directive. A block of consecutive comment lines only needs one blank line, above the first.
The comment directly follows an opening brace (the first line of a block), the [ of a collection expression, or a case/default label.
The comment directly follows => (a switch expression arm, a lambda or an expression body): it starts what comes after the arrow, like a comment after {.
//// commented-out code and /// comments.
Trailing comments (x++; // note), which don't start their line, and a comment that continues a trailing comment in the line below, starting in the same column: a blank line would split the sentence.
A comment above a switch section (return;, // note, case 2:) when stylebro_blank_line_between_switch_sections (BRO1526) wants no blank line between the sections.

Unlike StyleCop:

A comment below code: a run of // lines right below a line that ends with ;, followed by a blank line. It describes the code above it (eShop: a note below a field, then a blank line, then a method); moving the blank line above it would attach it to the code below. StyleCop reports it.
A comment between the links of a call chain: the next token is the . or ?. of a member access, as in builder.Services.AddHealthChecks(), // Add a default liveness check, .AddCheck(...) (davidfowl/TodoApi). The comment describes the next link, and a blank line would split the chain. StyleCop reports it.
A comment between the items of a list: right after the list's (, [, { or a ,, or right before a , or the list's closing token, in argument, indexer argument, attribute argument, parameter, initializer (object, collection, array), collection expression and tuple lists (Path.Join(dir, "game.json"),, // options for ..., new JsonSerializerOptions()). The comment describes the next item, and a blank line would split the list. StyleCop reports it.

A comment after an ordinary label: is reported, like in StyleCop.

Compared with StyleCop¶

Same results as StyleCop 1.2.0-beta.556, except a comment right after a collection expression's [: beta.556 reports it, StyleBro treats [ like { (as StyleCop's unreleased fix for #3766 does), and a comment right after =>: StyleCop reports it and its fix puts a blank line between the arrow and the comment (#3392, open; for expression bodies #3550), and a comment between call chain links or list items (above). Both only make StyleBro quieter, so a StyleCop-clean repository stays clean.