C# KONGOR Project Style Guide

This skill enforces the comprehensive coding standards for Project KONGOR's open-source C# codebase, ensuring consistency across syntax, formatting, naming, and code generation practices.

Naming Conventions

Acronyms and Initialisms

**PascalCase**: Always use uppercase for acronyms and initialisms

- Correct: `UserID`, `GetGUID`, `HTMLParser`

- Incorrect: `UserId`, `GetGuid`, `HtmlParser`

**camelCase**: Only use uppercase if NOT at the start of the symbol name

- Correct: `userGUID`, `accountID`, `httpStatusCode`

- Incorrect: `userGuid`, `accountId`, `hTTPStatusCode`

Variable Names

**No abbreviations**: Always use full words

- Correct: `configuration`, `administrator`, `implementation`

- Incorrect: `config`, `admin`, `impl`

**Lambda parameters**: Always use full, descriptive names

- Correct: `numbers.Select(number => number * number)`

- Incorrect: `numbers.Select(x => x * x)`

Async Methods

Only suffix with "Async" when a synchronous version exists in the same scope

Formatting Rules

Basic Formatting

Never use `var` — always use explicit type names

Use four spaces for indentation (never tabs)

Always terminate files with a newline character

Keep vertical whitespace consistent with surrounding code

Switch Expression Alignment

Align lambda operators in switch expressions:

```csharp

return UserType switch

{

UserType.Staff => "internal",

UserType.Client => "external",

_ => throw new ArgumentOutOfRangeException($"Unsupported User Type \"{UserType}\"")

};

```

Comments and Documentation

Code Comments

Use StartCase for comments (capitalize first letter of each word)

Preserve original casing for acronyms, initialisms, and symbol names

Only add comments when they provide non-obvious value

Enclose symbol names in double quotes when not using `<see cref="..."/>`

Example:

```csharp

// This Is A Sample Comment Explaining The Purpose Of The "request" Variable In The HTTP Handler

```

XML Documentation

Use sentence case with proper indentation

Include punctuation at the end of each sentence

Use `<see cref="..."/>` tags for symbol references (without parameters)

Example:

```csharp

/// <summary>

/// This method retrieves user information based on the provided user ID.

/// It does so by using the "request" variable from the HTTP handler.

/// </summary>

```

Correct `<see cref="..."/>` usage:

Correct: `<see cref="CalculateTotal"/>`

Incorrect: `<see cref="CalculateTotal(int, int)"/>`

Language and Literals

Always use British English (never American English)

- Correct: "colour", "optimise", "behaviour"

- Incorrect: "color", "optimize", "behavior"

Refer to literals in uppercase in comments:

- Use "TRUE", "FALSE", "NULL" to distinguish from natural language

Null Handling

Never use the null-forgiving operator (`!`) except in these cases:

1. Entity Framework queries with `Include`/`ThenInclude` for navigation properties known to be non-null

2. When assigning `null!` is unavoidable without excessive complexity AND runtime null is guaranteed impossible

Using Directives

Prefer global using directives

Place in `Internals/UsingDirectives.cs` at project root

Sort lexicographically in ascending order, grouped by assembly

Use `global using` syntax (not `global::` alias)

Example:

```csharp

global using Aspire.Hosting;

global using Microsoft.Extensions.DependencyInjection;

```

Code Generation Principles

Core Requirements

1. **Correctness**: Ensure syntactic correctness and adherence to language best practices

2. **Performance**: Optimise for efficiency unless it compromises readability

3. **Security**: Follow best practices to prevent vulnerabilities (injection, leaks, unauthorized access)

4. **Consistency**: Match existing codebase style, conventions, and architecture

5. **Targeted**: Avoid unnecessary features or complexity

Design Philosophy

**Prefer simplicity**: Keep code straightforward and easy to understand

**Avoid over-engineering**: Don't add features not explicitly requested

**Minimalism**: Avoid unnecessary abstractions, layers, or components

**Clarity over cleverness**: Choose readable solutions over complex optimizations

Verification Process

When generating code:

1. Check relevant online sources or documentation when needed

2. Inspect existing codebase for patterns to follow

3. Review the prompt to ensure alignment with objectives

4. Present options to the user when ambiguity exists

Enforcement Workflow

When reviewing or generating C# code for Project KONGOR:

1. Verify all naming conventions match the acronym/initialism rules

2. Check indentation is exactly four spaces

3. Confirm British English usage throughout

4. Validate lambda parameters use full descriptive names

5. Ensure comments use StartCase and XML docs use sentence case

6. Check `<see cref="..."/>` tags omit parameters

7. Verify global using directives are in `Internals/UsingDirectives.cs`

8. Confirm consistency with surrounding code style

9. Review for unnecessary complexity or features

C# KONGOR Project Style Guide

C# KONGOR Project Style Guide

Naming Conventions

Acronyms and Initialisms

Variable Names

Async Methods

Formatting Rules

Basic Formatting

Switch Expression Alignment

Comments and Documentation

Code Comments

XML Documentation

Language and Literals

Null Handling

Using Directives

Code Generation Principles

Core Requirements

Design Philosophy

Verification Process

Enforcement Workflow

Reviews (0)