Coding Conventions and Documentation

public sealed class Catalogue
{
    private readonly Dictionary<string, string> _entries = new();

    // General in, specific out; never null.
    public IReadOnlyList<string> Find(IEnumerable<string> keys) =>
        keys.Where(_entries.ContainsKey).ToList();

    // Exceptional failure: throw.
    public string Get(string key) =>
        _entries.TryGetValue(key, out string? value)
            ? value
            : throw new KeyNotFoundException($"No entry for '{key}'.");

    // Expected failure: the Try pattern, no exception.
    public bool TryGet(string key, out string? value) => _entries.TryGetValue(key, out value);
}

using System;
using System.Collections.Generic;

namespace Irurueta.Sample.Layout;

public sealed class Formatter
{
    private readonly IReadOnlyList<string> _parts;

    public Formatter(IReadOnlyList<string> parts)
    {
        ArgumentNullException.ThrowIfNull(parts);

        _parts = parts;
    }

    public string Render(string separator)
    {
        if (_parts.Count == 0)
        {
            return string.Empty;
        }

        return string.Join(separator, _parts);
    }
}

root = true

[*]
indent_style = space
insert_final_newline = true
charset = utf-8

[*.{cs,csx}]
indent_size = 4
max_line_length = 120

# Formatting.
csharp_new_line_before_open_brace = all
csharp_indent_case_contents = true
csharp_space_after_keywords_in_control_flow_statements = true
dotnet_sort_system_directives_first = true
csharp_using_directive_placement = outside_namespace:warning

# Language style preferences, each with a severity.
csharp_style_namespace_declarations = file_scoped:warning
csharp_style_var_for_built_in_types = false:suggestion
csharp_style_var_when_type_is_apparent = true:suggestion
csharp_style_expression_bodied_methods = when_on_single_line:suggestion
csharp_prefer_braces = true:warning
dotnet_style_null_propagation = true:suggestion
dotnet_style_coalesce_expression = true:suggestion
dotnet_style_prefer_is_null_check_over_reference_equality_method = true:suggestion
csharp_style_prefer_pattern_matching = true:suggestion
dotnet_style_readonly_field = true:warning

# Naming: private fields must be _camelCase.
dotnet_naming_rule.private_fields_underscore.symbols = private_fields
dotnet_naming_rule.private_fields_underscore.style = underscore_camel
dotnet_naming_rule.private_fields_underscore.severity = warning

dotnet_naming_symbols.private_fields.applicable_kinds = field
dotnet_naming_symbols.private_fields.applicable_accessibilities = private

dotnet_naming_style.underscore_camel.required_prefix = _
dotnet_naming_style.underscore_camel.capitalization = camel_case

# Individual analyzer rules.
dotnet_diagnostic.CA1062.severity = warning     # validate public arguments
dotnet_diagnostic.IDE0055.severity = warning    # formatting

<PropertyGroup>
  <EnableNETAnalyzers>true</EnableNETAnalyzers>
  <AnalysisLevel>latest</AnalysisLevel>
  <AnalysisMode>Recommended</AnalysisMode>
  <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
</PropertyGroup>

dotnet format                       # whitespace, style and analyzer fixes
dotnet format --verify-no-changes   # CI gate: fail if anything would change
dotnet format style --severity warn
dotnet format analyzers --diagnostics CA1062

using System.Diagnostics.CodeAnalysis;

public static class Suppressions
{
    [SuppressMessage(
        "Globalization", "CA1305:Specify IFormatProvider",
        Justification = "This value is a protocol token, never displayed to a user.")]
    public static string Format(int value) => value.ToString();
}

namespace Irurueta.Sample.Documented;

/// <summary>
/// Computes summary statistics over a sequence of samples.
/// </summary>
/// <remarks>
/// Instances are immutable and safe to share between threads. For streaming data, prefer
/// <see cref="StreamingStatistics"/>, which does not retain the samples.
/// </remarks>
public sealed class Statistics
{
    private readonly IReadOnlyList<double> _samples;

    /// <summary>
    /// Initializes a new instance of the <see cref="Statistics"/> class.
    /// </summary>
    /// <param name="samples">The samples to summarise. The sequence is copied.</param>
    /// <exception cref="ArgumentNullException"><paramref name="samples"/> is <see langword="null"/>.</exception>
    public Statistics(IEnumerable<double> samples)
    {
        ArgumentNullException.ThrowIfNull(samples);

        _samples = samples.ToList();
    }

    /// <summary>
    /// Gets the number of samples.
    /// </summary>
    /// <value>The sample count, which is never negative.</value>
    public int Count => _samples.Count;

    /// <summary>
    /// Computes the arithmetic mean of the samples.
    /// </summary>
    /// <returns>The mean of the samples.</returns>
    /// <exception cref="InvalidOperationException">The instance holds no samples.</exception>
    /// <example>
    /// The following example computes the mean of three samples:
    /// <code>
    /// var statistics = new Statistics([1.0, 2.0, 3.0]);
    /// Console.WriteLine(statistics.Mean());   // 2
    /// </code>
    /// </example>
    /// <seealso cref="Count"/>
    public double Mean() =>
        _samples.Count > 0
            ? _samples.Average()
            : throw new InvalidOperationException("No samples.");
}

/// <summary>
/// Computes statistics incrementally, without retaining the samples.
/// </summary>
public sealed class StreamingStatistics
{
}

dotnet tool install -g docfx

docfx init --yes            # scaffolds docfx.json, a docs/ folder and a toc.yml
docfx docfx.json --serve    # generates the site and serves it locally

{
  "metadata": [
    {
      "src": [ { "files": [ "src/**/*.csproj" ] } ],
      "dest": "api"
    }
  ],
  "build": {
    "content": [
      { "files": [ "api/**.yml", "api/index.md" ] },
      { "files": [ "articles/**.md", "toc.yml", "*.md" ] }
    ],
    "dest": "_site"
  }
}

public static class Guards
{
    public static string Normalise(string? text, int maxLength)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(text);
        ArgumentOutOfRangeException.ThrowIfNegativeOrZero(maxLength);

        return text.Trim()[..Math.Min(text.Trim().Length, maxLength)];
    }
}

public sealed class Temperature(double celsius)
{
    public double Celsius { get; } = celsius;

    public double Fahrenheit => Celsius * 9 / 5 + 32;

    public override string ToString() => $"{Celsius:F1} °C";
}

public static class VarGuidance
{
    public static void Show(IEnumerable<string> source)
    {
        var builder = new System.Text.StringBuilder();       // obvious
        var items = new List<string>(source);                // obvious

        int count = items.Count;                             // explicit: small and clear
        IReadOnlyList<string> result = items.AsReadOnly();   // explicit: the type is the point

        Console.WriteLine((builder.Length, count, result.Count));
    }
}

public static class NullChecks
{
    public static string Describe(object? value) =>
        value is null ? "nothing"
        : value is string text ? $"text: {text}"
        : "something";
}

public sealed class Configured
{
    private readonly Dictionary<string, List<int>> _groups = new();
    private readonly string[] _defaults = ["alpha", "beta"];

    public void Add(string key, int value)
    {
        if (!_groups.TryGetValue(key, out List<int>? values))
        {
            values = [];
            _groups[key] = values;
        }

        values.Add(value);
    }

    public IReadOnlyList<string> Defaults => _defaults;
}