C# Coding Guidelines for Project KONGOR

This skill enforces comprehensive C# coding standards for the Project KONGOR open-source project. It covers syntax, formatting, naming conventions, British English usage, and code generation principles to maintain consistency and quality across the codebase.

Instructions

When writing or reviewing C# code for Project KONGOR, enforce the following guidelines:

1. Type Declarations and Variable Usage

Never use `var`. Always use explicit type names.

Use four spaces for indentation (never tabs).

Always terminate files with a newline character.

2. Naming Conventions

**Acronyms and Initialisms:**

In PascalCase: always uppercase the entire acronym/initialism

- ✅ `UserID`, `GetGUID`, `HTMLParser`

- ❌ `UserId`, `GetGuid`, `HtmlParser`

In camelCase: only uppercase if NOT at the start of the name

- ✅ `userGUID`, `accountID`, `httpStatusCode`

- ❌ `userGuid`, `accountId`, `hTTPStatusCode`

**Delegates and Lambda Parameters:**

Always use full, descriptive variable names. Never use abbreviations or single-letter names.

- ✅ `numbers.Select(number => number * number);`

- ❌ `numbers.Select(x => x * x);`

**Symbol Names:**

Always use full words, never abbreviations.

- ✅ `configuration`, `administrator`, `implementation`

- ❌ `config`, `admin`, `impl`

**Async Methods:**

Never use the "Async" suffix unless there's also a synchronous version in the same scope.

3. Code Formatting

**Vertical Whitespace:**

Keep vertical whitespace usage consistent with existing code in the proximity.

**Switch Expressions:**

Always align lambda operators:

```csharp

return UserType switch

{

UserType.Staff => "internal",

UserType.Client => "external",

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

};

```

**Using Directives:**

Always prefer global using directives.

Add or move them to `Internals/UsingDirectives.cs` in the project root.

Keep in lexicographic order ascending, grouped by assembly.

Use global using directive syntax:

- ✅ `global using Aspire.Hosting;`

- ❌ `using global::Aspire.Hosting;`

4. Comments and Documentation

**Code Comments:**

Only add comments when they provide value (explain WHY, not WHAT).

Use StartCase, but preserve acronyms, initialisms, and symbol names:

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

Enclose symbol names, branch names, etc. in double quotation marks unless using `<see cref="..."/>`.

**XML Documentation Summaries:**

Use sentence case with correct indentation and punctuation.

End each sentence with a punctuation mark.

Format:

```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>

```

**See Cref Tags:**

When referencing methods, do NOT include parameters:

- ✅ `<see cref="CalculateTotal"/>`

- ❌ `<see cref="CalculateTotal(int, int)"/>`

5. Language and Spelling

Always use British English (never American English).

- ✅ `colour`, `optimise`, `realise`

- ❌ `color`, `optimize`, `realize`

In comments, use `TRUE`, `FALSE`, and `NULL` (uppercase) when referring to literals.

6. Null Handling

**Null-Forgiving Operator (!):**

Never use to suppress null handling EXCEPT:

- When using `Include` or `ThenInclude` in Entity Framework queries for navigation properties known to be non-null.

- When assigning `null!` is unavoidable without making code overly complex AND runtime null is impossible.

7. Code Generation Principles

When generating code:

**Correctness:**

Ensure syntactic correctness and adherence to best practices.

Check online sources or documentation when needed.

**Performance:**

Optimise for performance unless it significantly compromises readability or maintainability.

**Security:**

Follow best practices to prevent injection attacks, data leaks, and unauthorised access.

Verify compliance with latest security standards when possible.

**Consistency:**

Match existing codebase style, conventions, and architecture.

Inspect existing code to identify patterns to follow.

**Targeted Implementation:**

Focus on the objective without adding unnecessary features or complexity.

When in doubt, present options clearly and let the user decide.

**Simplicity Over Complexity:**

Prefer clarity over unnecessary features.

Avoid over-engineering or adding unrequested features.

Keep code straightforward, minimalistic, and easy to understand.

Avoid unnecessary abstractions, layers, or components.

Examples

Good Variable Naming

```csharp

public async Task<User> GetUserByID(int userID)

{

return await users.FirstOrDefault(user => user.ID == userID);

}

```

Switch Expression Alignment

```csharp

return role switch

{

Role.Administrator => AccessLevel.Full,

Role.Moderator => AccessLevel.Limited,

Role.User => AccessLevel.Basic,

_ => throw new ArgumentException(@$"Unknown role ""{role}""")

};

```

Documentation Example

```csharp

/// <summary>

/// Retrieves the user's configuration settings from the database.

/// If no configuration exists, creates a default configuration and returns it.

/// </summary>

/// <param name="userID">The unique identifier for the user.</param>

/// <returns>The user's configuration object.</returns>

public async Task<Configuration> GetUserConfiguration(int userID)

{

// Implementation Here

}

```

Constraints

These guidelines apply specifically to the Project KONGOR codebase.

Consistency with existing code takes priority—always inspect nearby code first.

When guidelines conflict with existing patterns, match the existing code and flag for team discussion.

C# Coding Guidelines for Project KONGOR

C# Coding Guidelines for Project KONGOR

Instructions

1. Type Declarations and Variable Usage

2. Naming Conventions

3. Code Formatting

4. Comments and Documentation

5. Language and Spelling

6. Null Handling

7. Code Generation Principles

Examples

Good Variable Naming

Switch Expression Alignment

Documentation Example

Constraints

Reviews (0)