cratis-engineering-csharp-conventions

Cratis C# engineering conventions

These are the house conventions Cratis maintainers apply across every repository. They are conventions, not framework contracts: nothing here is enforced by an analyzer unless this skill says so. Follow them for consistency; do not claim the framework requires them.

Route near misses

• The question is what a Cratis product API does: resolve it against the owning product repository, not against this style guide.
• The subject is a specification file: the specification conventions own the Establish/Because/should_ pattern and the for_/when_ hierarchy.
• The subject is TypeScript or React: this skill covers C# only.
• The subject is repository structure or documentation: those are separate workflows.

Quick reference

• Use current C# language features — records, primary constructors, pattern matching, collection expressions.
• var over an explicit type; the right-hand side already names the type.
• File-scoped namespace declarations.
• using directives alphabetically sorted, single-line, unused ones removed.
• No regions. A file that needs them needs refactoring instead.
• No technical postfixes on type names: no Impl, Service, Manager, Handler, Base, Async.
• No Exception suffix on exception types — AuthorNotFound, not AuthorNotFoundException.
• Never throw a built-in exception type. Always define a domain exception.
• record for events, commands, read models, concepts, and DTOs.
• is null and is not null — never == null or != null.
• Blank line before the opening { of every block.
• A final return sits on its own line.
• Private fields are _camelCase; interfaces take the I prefix.
• American English everywhere — initialize, behavior, color, serialize.
• Every file starts with the repository license header.

Formatting

// Copyright (c) Cratis. All rights reserved.
// Licensed under the MIT license. See LICENSE file in the project root for full license information.

namespace <RootNamespace>.<Feature>;

using <Namespace>.<First>;
using <Namespace>.<Second>;

// Blank line before the opening brace of every block
if (<condition>)
{
    <statement>;
}

// Expression-bodied form for simple members
public string <PropertyName> => $"{<First>} {<Second>}";

// The final return stands alone
public <ReturnType> <MethodName>()
{
    var result = <expression>;

    return result;
}