Coree.Analyzers.CodeClarity 1.0.5

Coree.Analyzers.CodeClarity

A return expression should stay directly readable, including one written with =>. This package flags one that exceeds the allowed number of calculation steps. A parameter list has two shapes: the whole list on one line, parentheses included, or each parameter on its own line with the closing parenthesis on the following line. A type declared directly in a file must sit in a namespace. Consecutive methods in a type keep a blank line between them.

dotnet add package Coree.Analyzers.CodeClarity

Example in a project file. The version 0.1.2 is the one shown here:

<ItemGroup>
  <PackageReference Include="Coree.Analyzers.CodeClarity" Version="0.1.2">
    <PrivateAssets>all</PrivateAssets>
    <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
  </PackageReference>
</ItemGroup>

Diagnostics

Arithmetic other than string concatenation, method calls other than nameof, and conditional operators each count as one step. A user-defined operator + counts even when one operand is a string. Casts, signs, await, member access, and identifiers do not. Default severity is warning.

Only the C# nameof operator is exempt. A user-defined method named nameof (including @nameof) counts as a method call. For example, return @nameof(a + b); has two steps and reports at the default maximum of 1.

Each shift operator (<<, >>, and >>>) also counts as one step. At the default maximum, return value >>> count stays quiet, while return value >>> (count + extra) reports CCCRC001.

At the default maximum of 1, return a + b stays quiet, and so does return total. return a + b + c reports CCCRC001. total is a local; that return is only the name. A yield return expression uses that same score. yield return a + b stays quiet, and yield return a + b + c reports CCCRC001.

An expression-bodied member uses that same score when the arrow expression is the returned value. int Height(int a, int b, int c) => a + b + c reports at the default maximum. int Height(int a, int b) => a + b stays quiet. A void arrow, a constructor, a setter, a lambda, and an async method that returns a non-generic Task or ValueTask stay quiet, because those arrows are not returned values.

int OneStep(int a, int b)
{
    return a + b;
}

int TwoSteps(int a, int b, int c)
{
    return a + b + c;
}

int FromLocal(int a, int b, int c)
{
    int total = a + b + c;
    return total;
}

CCCPL001 looks at methods, local functions, constructors, and primary constructors of classes, structs, and records. Calls, indexers, delegates, and lambdas stay out of it. An empty list and a single parameter stay quiet. The first two samples report CCCPL001. The other two do not: one line, parentheses included, or one parameter per line with the closing parenthesis on the following line. A parameter that began higher still shares a line when the next parameter sits on its last line, and that list reports CCCPL001. The same parameter stays quiet when the next one starts on a later line.

public void M(
    float a,
    float b,
    float c)

public void M(
    float a, float b, float c)

public record TerrainProfile(float Amplitude, float FrequencyX, float FrequencyZ, float DetailAmplitude, float DetailX, float DetailZ);

public void M(
    float a,
    float b,
    float c
)

The closing parenthesis follows the last line of the last parameter. An attribute or a default may occupy earlier lines of that parameter. This stays quiet:

public void M(
    int a,
    [NotNull]
    int b
)

This reports CCCPL001, because ) is on that parameter's last line:

public void M(
    int a,
    [NotNull]
    int b)

CCCPL002 is separate from that shape rule. The last sample stays within CCCPL001 and still reports CCCPL002, because the parameters would fit on one line. The length is the parameters joined by , after tabs, line breaks, and repeated spaces collapse. Whitespace inside literals is kept. Parentheses are not counted. A list that contains a // comment or a preprocessor directive stays quiet, because that trivia cannot be kept on the one line the diagnostic recommends. A // or #if inside a string is not a comment or a directive and can still report. A literal that contains a line break also stays quiet. CR, LF, next line (U+0085), line separator (U+2028), and paragraph separator (U+2029) are part of the value, whether the literal is verbatim, raw, or interpolated. An escaped \n in a regular string is not that line break, so the list can still report. float a, float b, float c is 25 characters, so it reports at the default of 120. The one-line record does not. A longer list that uses the same legal break stays quiet.

CCCNS001 reports a class, struct, record, interface, enum, or delegate that is not inside a namespace. Nested types are not reported on their own. The first sample reports CCCNS001. The block namespace and the file-scoped namespace do not.

class Terrain { }

namespace Game
{
    class Terrain { }
}

namespace Game;

class Terrain { }

CCCMB001 reports the later of two methods with a body that are consecutive members of the same type and have no blank line between them. A whitespace-only line counts. A comment or documentation line does not. The first sample reports CCCMB001. The second does not. Constructors, fields, properties, operators, indexers, local functions, and methods without a body stay quiet.

Blank lines are recognized with all C# line endings: LF, CRLF, CR, next line (U+0085), line separator (U+2028), and paragraph separator (U+2029), including mixed endings within a file.

public bool Walkable()
{
    return true;
}
private bool StaticSegmentClear()
{
    return true;
}

public bool Walkable()
{
    return true;
}

private bool StaticSegmentClear()
{
    return true;
}

MSBuild properties

Set these on the consuming compile target. The shipped props make them compiler-visible. Severity: warning, error, message, or off. An empty, negative, or non-numeric maximum keeps that analyzer's default: 1 calculation step, or 120 characters for CCCPL002.

<PropertyGroup>
  <ReturnTypeComplexityAnalyzerSeverity>warning</ReturnTypeComplexityAnalyzerSeverity>
  <ReturnTypeComplexityAnalyzerMaximum>1</ReturnTypeComplexityAnalyzerMaximum>
  <ParameterListLayoutAnalyzerSeverity>warning</ParameterListLayoutAnalyzerSeverity>
  <ParameterListFitAnalyzerSeverity>warning</ParameterListFitAnalyzerSeverity>
  <ParameterListFitAnalyzerMaximum>120</ParameterListFitAnalyzerMaximum>
  <TypeNamespaceAnalyzerSeverity>warning</TypeNamespaceAnalyzerSeverity>
  <MethodBlankLineAnalyzerSeverity>warning</MethodBlankLineAnalyzerSeverity>
</PropertyGroup>

Repository: https://github.com/carsten-riedel/Coree.Analyzers

License: MIT