# .NET Complexity and Maintainability Rules

## Open/Free Status

- first-party .NET analyzers
- free to use with the .NET SDK

## Best Answer for Complex Methods

If the question is "which analyzer finds methods that are too complex?", the primary built-in answer is:

- `CA1502` for excessive cyclomatic complexity

Closely related maintainability rules:

- `CA1505` for low maintainability index
- `CA1506` for excessive class coupling
- `CA1501` for excessive inheritance depth

## Verify First

Before adding anything, check whether the repo already configures these rules:

```bash
rg -n "CA1501|CA1502|CA1505|CA1506|CodeMetricsConfig" -g '.editorconfig' -g '*.csproj' -g 'Directory.Build.*' .
rg --files -g 'CodeMetricsConfig.txt'
```

## Root .editorconfig

Keep severity in the repo-root `.editorconfig`, for example:

```ini
root = true

[*.cs]
dotnet_diagnostic.CA1502.severity = warning
dotnet_diagnostic.CA1505.severity = warning
dotnet_diagnostic.CA1506.severity = warning
dotnet_diagnostic.CA1501.severity = suggestion
```

## Threshold Configuration

Thresholds for these code-metrics rules are configured through a checked-in `CodeMetricsConfig.txt` file, for example:

```text
CA1502: 20
CA1502(Type): 6
CA1505: 10
CA1506: 30
CA1506(Type): 80
CA1501: 6
```

Then include it in the project:

```xml
<ItemGroup>
  <AdditionalFiles Include="CodeMetricsConfig.txt" />
</ItemGroup>
```

## CI Fit

- use `dotnet build` as the enforcement path
- keep thresholds checked in
- treat `CA1502` as the main answer for overly complex methods, not as a vanity metric

## When Not To Use

- when the repo only wants stylistic linting and does not intend to act on maintainability findings

## Sources

- [CA1502: Avoid excessive complexity](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/quality-rules/ca1502)
- [CA1505: Avoid unmaintainable code](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/quality-rules/ca1505)
- [CA1506: Avoid excessive class coupling](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/quality-rules/ca1506)
- [CA1501: Avoid excessive inheritance](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/quality-rules/ca1501)
- [Code metrics values](https://learn.microsoft.com/en-us/visualstudio/code-quality/code-metrics-values?view=vs-2022)

# Analyzer Configuration for Complexity Rules

## Configuration Layers

Complexity analyzers can be configured at multiple levels:

1. **EditorConfig** - rule severity
2. **CodeMetricsConfig.txt** - numeric thresholds
3. **Project/Directory.Build.props** - analyzer package inclusion

## EditorConfig Setup

### Minimal Configuration

Add to root `.editorconfig`:

```ini
root = true

[*.cs]
dotnet_diagnostic.CA1502.severity = warning
dotnet_diagnostic.CA1505.severity = warning
dotnet_diagnostic.CA1506.severity = warning
dotnet_diagnostic.CA1501.severity = suggestion
```

### Severity Levels

| Severity   | Build Behavior                     | Use Case                           |
|------------|------------------------------------|------------------------------------|
| error      | Fails the build                    | Hard enforcement in CI             |
| warning    | Shows warning, build succeeds      | Recommended default                |
| suggestion | Shows message in IDE only          | Informational tracking             |
| silent     | Runs but produces no diagnostics   | Metric collection without noise    |
| none       | Completely disabled                | Intentionally ignored              |

### Per-File Overrides

To relax rules for generated or legacy code:

```ini
[*.generated.cs]
dotnet_diagnostic.CA1502.severity = none
dotnet_diagnostic.CA1505.severity = none
dotnet_diagnostic.CA1506.severity = none

[**/Migrations/*.cs]
dotnet_diagnostic.CA1502.severity = silent
```

## CodeMetricsConfig.txt

### File Format

The `CodeMetricsConfig.txt` file specifies numeric thresholds:

```text
# Cyclomatic complexity per method
CA1502: 20

# Cyclomatic complexity average per type
CA1502(Type): 6

# Maintainability index minimum
CA1505: 10

# Class coupling per method
CA1506: 30

# Class coupling per type
CA1506(Type): 80

# Inheritance depth maximum
CA1501: 6
```

### Scope Suffixes

| Suffix       | Meaning                                |
|--------------|----------------------------------------|
| (none)       | Per-method threshold                   |
| `(Type)`     | Per-type or type-average threshold     |
| `(Assembly)` | Assembly-wide threshold (where applicable) |

### Threshold Recommendations

**Conservative (new projects):**

```text
CA1502: 15
CA1502(Type): 5
CA1505: 20
CA1506: 20
CA1506(Type): 50
CA1501: 4
```

**Moderate (established projects):**

```text
CA1502: 20
CA1502(Type): 6
CA1505: 10
CA1506: 30
CA1506(Type): 80
CA1501: 6
```

**Relaxed (legacy migration):**

```text
CA1502: 30
CA1502(Type): 10
CA1505: 5
CA1506: 50
CA1506(Type): 120
CA1501: 8
```

## Project Integration

### Including CodeMetricsConfig.txt

Add to `Directory.Build.props` for solution-wide application:

```xml
<Project>
  <ItemGroup>
    <AdditionalFiles Include="$(MSBuildThisFileDirectory)CodeMetricsConfig.txt"
                     Condition="Exists('$(MSBuildThisFileDirectory)CodeMetricsConfig.txt')" />
  </ItemGroup>
</Project>
```

Or add to individual `.csproj` files:

```xml
<ItemGroup>
  <AdditionalFiles Include="../../CodeMetricsConfig.txt" />
</ItemGroup>
```

### Analyzer Package Reference

The maintainability rules require the .NET analyzers. For SDK-style projects targeting .NET 5+, these are included by default.

For older projects or explicit inclusion:

```xml
<PropertyGroup>
  <EnableNETAnalyzers>true</EnableNETAnalyzers>
  <AnalysisLevel>latest</AnalysisLevel>
  <AnalysisMode>Recommended</AnalysisMode>
</PropertyGroup>
```

Or reference the package directly:

```xml
<ItemGroup>
  <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="9.*">
    <PrivateAssets>all</PrivateAssets>
    <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
  </PackageReference>
</ItemGroup>
```

## Suppression Strategies

### Attribute-Based Suppression

For intentional violations:

```csharp
[SuppressMessage("Maintainability", "CA1502:Avoid excessive complexity",
    Justification = "State machine requires explicit transitions")]
public void ProcessState() { ... }
```

### Global Suppressions

Add to `GlobalSuppressions.cs`:

```csharp
[assembly: SuppressMessage("Maintainability", "CA1506:Avoid excessive class coupling",
    Scope = "type", Target = "~T:MyNamespace.CompositionRoot",
    Justification = "Composition root is expected to have high coupling")]
```

### Pragma Suppression

For localized suppression:

```csharp
#pragma warning disable CA1502
public void LegacyMethod()
{
    // Complex legacy code pending refactoring
}
#pragma warning restore CA1502
```

## CI Integration

### Build Command

```bash
dotnet build -warnaserror
```

### Selective Error Promotion

To fail only on complexity rules:

```xml
<PropertyGroup>
  <WarningsAsErrors>CA1502;CA1505;CA1506</WarningsAsErrors>
</PropertyGroup>
```

### Baseline Workflow

For existing codebases:

1. Set all rules to `suggestion`
2. Run `dotnet build` and capture baseline counts
3. Add `CodeMetricsConfig.txt` with current thresholds
4. Gradually tighten thresholds as code improves
5. Promote to `warning` when baseline is acceptable
6. Promote to `error` when enforcement is stable

## Sources

- [Configure code analysis rules](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/configuration-options)
- [EditorConfig settings](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/code-style-rule-options)
- [Suppress code analysis warnings](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/suppress-warnings)

# .NET Code Complexity Metrics

## Overview

.NET provides built-in code metrics through the Roslyn analyzers. These metrics quantify maintainability, complexity, and coupling without requiring third-party tools.

## Primary Metrics

### Cyclomatic Complexity (CA1502)

Cyclomatic complexity measures the number of linearly independent paths through a method's source code.

**Calculation:**

- Start with 1
- Add 1 for each: `if`, `else if`, `case`, `while`, `for`, `foreach`, `&&`, `||`, `??`, `?.`, `catch`, conditional expression (`? :`)

**Thresholds:**

| Range   | Risk Level |
|---------|------------|
| 1-10    | Low        |
| 11-20   | Moderate   |
| 21-50   | High       |
| 51+     | Very High  |

**Recommended default:** 20 for methods, 6 for type average.

**Refactoring signals:**

- Extract method for distinct logic branches
- Replace conditional chains with polymorphism or strategy pattern
- Simplify boolean expressions

### Maintainability Index (CA1505)

The maintainability index is a composite metric ranging from 0 to 100 that indicates overall code maintainability.

**Formula:**

```
MI = MAX(0, (171 - 5.2 * ln(HV) - 0.23 * CC - 16.2 * ln(LOC)) * 100 / 171)
```

Where:
- HV = Halstead Volume (based on operators and operands)
- CC = Cyclomatic Complexity
- LOC = Lines of Code

**Thresholds:**

| Range   | Maintainability |
|---------|-----------------|
| 20-100  | High            |
| 10-19   | Moderate        |
| 0-9     | Low             |

**Recommended default:** 10 minimum.

**Refactoring signals:**

- Large methods need decomposition
- Complex expressions need simplification
- Consider extracting classes for low-scoring types

### Class Coupling (CA1506)

Class coupling counts the number of unique types that a type or method references, excluding primitives and common framework types.

**What counts as coupling:**

- Base types
- Interface implementations
- Parameter types
- Local variable types
- Method return types
- Generic type arguments
- Exception types

**What is excluded:**

- Primitive types (`int`, `string`, `bool`, etc.)
- `System.Object`
- `System.Void`

**Thresholds:**

| Scope  | Recommended Maximum |
|--------|---------------------|
| Method | 30                  |
| Type   | 80                  |

**Refactoring signals:**

- Introduce abstractions to reduce direct dependencies
- Apply dependency injection
- Split large classes by responsibility

### Inheritance Depth (CA1501)

Inheritance depth counts the number of types in the inheritance chain, starting from `System.Object`.

**Thresholds:**

| Depth | Risk Level |
|-------|------------|
| 1-4   | Low        |
| 5-6   | Moderate   |
| 7+    | High       |

**Recommended default:** 6 maximum.

**Refactoring signals:**

- Prefer composition over deep inheritance
- Flatten hierarchies where intermediate classes add little value

## Metric Interactions

These metrics often correlate:

- High cyclomatic complexity typically lowers the maintainability index
- High coupling often accompanies high complexity
- Deep inheritance can mask complexity in base classes

When multiple metrics flag the same code:

1. Address cyclomatic complexity first (most actionable)
2. Coupling improvements often follow complexity reduction
3. Maintainability index improves as other metrics improve

## Lines of Code

Lines of code (LOC) is not enforced by a dedicated analyzer rule, but it factors into the maintainability index calculation.

**Guidelines:**

- Methods: prefer under 50 logical lines
- Types: prefer under 500 logical lines
- Files: prefer under 1000 logical lines

## Sources

- [Code metrics values](https://learn.microsoft.com/en-us/visualstudio/code-quality/code-metrics-values)
- [CA1502: Avoid excessive complexity](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/quality-rules/ca1502)
- [CA1505: Avoid unmaintainable code](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/quality-rules/ca1505)
- [CA1506: Avoid excessive class coupling](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/quality-rules/ca1506)
- [CA1501: Avoid excessive inheritance](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/quality-rules/ca1501)