coding-standards
/coding-standards
C# and .NET coding standards for generating new code files. Use when creating new classes, methods, controls, tests, or any new C# / VB source files in this repository. Covers C# 14 / .NET 10 patterns, naming, formatting, XML docs, WinForms conventions, and performance idioms.
- Author
- dotnet ↗
- Repository
- winforms ↗
- Licence
- MIT
- Last repository change
- 22.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 22.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
C# and .NET coding standards for generating new code files. Use when creating new classes, methods, controls, tests, or any new C# / VB source files in this repository. Covers C# 14 / .NET 10 patterns, naming, formatting, XML docs, WinForms conventions, and performance idioms.
Original author description
C# and .NET coding standards for generating new code files. Use when creating new classes, methods, controls, tests, or any new C# / VB source files in this repository. Covers C# 14 / .NET 10 patterns, naming, formatting, XML docs, WinForms conventions, and performance idioms.
How it works
- Target Framework
- Language Version
- General Assumptions
- Type Usage and var Policy
- Null Checking
- Naming and Field Conventions
- Formatting and Line Length
- Pattern Matching and Switch Expressions
- Readability
- Error Handling and Argument Validation
SKILL.md preview
---
name: coding-standards
description: >-
C# and .NET coding standards for generating new code files. Use when creating
new classes, methods, controls, tests, or any new C# / VB source files in this
repository. Covers C# 14 / .NET 10 patterns, naming, formatting, XML docs,
WinForms conventions, and performance idioms.
metadata:
author: dotnet-winforms
version: "1.0"
---
# Coding Standards — New Code Generation
These rules apply whenever you **generate new** C# or VB.NET source files in
this repository. For modernizing or refactoring *existing* files, see the
`code-modernization` skill instead.
## Target Framework
* Default target is **.NET 10.0** (`net10.0`).
* Some files target .NET Framework or are multi-targeted — check the project
file before generating.
* Do not edit files under `eng/common/`.
* Follow all rules defined in `.editorconfig`.
## Language Version
Use **C# 14** features and patterns. Key features to prefer:
| Feature | Example |
|---|---|
| Extension members (extension blocks) | `extension(string s) { public bool IsBlank() => ... }` |
| `field` keyword in properties | `set => field = value ?? throw ...;` |
| Null-conditional assignment | `customer?.Order = GetOrder();` |
| `nameof` on unbound generics | `nameof(List<>)` |
| Lambda modifiers without types | `(text, out result) => int.TryParse(text, out result)` |
| Partial constructors / events | `partial MyClass() { }` |
| First-class `Span<T>` conversions | Implicit `T[]` → `Span<T>` / `ReadOnlySpan<T>` |
## General Assumptions
* **Namespace imports** are defined in a global usings file — omit standard
`using` directives unless the import is non-obvious.
* **Nullable Reference Types** are enabled — annotate all new code accordingly.
* Use **file-scoped namespace** declarations.
## Type Usage and `var` Policy
Apply the following rules **in priority order**:
1. **Never use `var` for primitive types.** Always spell out `int`, `string`,
`bool`, `double`, `float`, `decimal`, `char`, `byte`, `long`, etc.
```csharp
// REQUIRED — explicit types for primitives
int count = 5;
string name = "Button";
bool isVisible = true;
```
2. **Use `var` when the type is already visible or clearly implied on the
same line.** Repeating the type degrades readability. This applies to:
* **Casts:** `var foo = (SomeType) bar;`
* **`as` casts:** `var button = item as ToolStripDropDownButton;`
* **Generic methods with explicit type argument(s):** Assume the return
type matches the generic type parameter — even when the method
signature technically returns a base type — because the `<T>` already
tells the reader what they are getting back:
`var host = this.GetService<IDesignerHost>();`
`var session = provider.GetRequiredService<DesignerSession>();`
* **`out var` in generic methods that name the type:**
`site.TryGetService<INestedContainer>(out var container)` — the `<T>`
already specifies the type.
* **Methods whose name contains or implies the return type:** When the
method name clearly communicates the type being returned, `var` is
preferred because the type is already readable from the call itself:
`var componentType = component.GetType();`
`var resourceStream = BitmapSelector.GetResourceStream(type, name);`
`TryLoadBitmapFromStream(stream, out var resourceBitmap)`
```csharp
// GOOD — var when type is visible or implied on the line
var designerHostShim = (IDesignerHostShim)designerHost;
var host = this.GetService<IDesignerHost>();
var manager = host.GetExport<ViewModelClientFactoryManager>();
var componentType = component.GetType();
var resourceStream = BitmapSelector.GetResourceStream(componentType, componentType.Name + ".bmp");
service.TryGetValue<AppSettings>(out var settings);
```
3. **Use `var` for deeply nested or complex generic types** where the full type
name is unwieldy:
```csharp
using var pooledList = ListPool<IComponent>.GetPooledObject();
var result = pooledList.Object;
var (key, value) = dictionary.First(); // tuple deconstruction
```
4. **Use explicit types when neither the variable name nor the surrounding
context reveals the type.** If a reader would need to navigate to a method
signature to understand what a variable holds, spell the type out.
```csharp
// REQUIRED — explicit when type is not obvious
CreateViewModelResponse response = session.GetWinFormsEndpoints().DocumentOutline.CreateViewModel(session.Id);
TreeViewHitTestInfo hitTestInfo = _treeView.HitTest(e.Location);
```
5. **Prefer target-typed `new()` over `var`** when the type is visible on the
left — clean construction without redundancy:
```csharp
// Before
Dictionary<string, List<int>> map = new Dictionary<string, List<int>>();
var map = new Dictionary<string, List<int>>();
// After
Dictionary<string, List<int>> map = new();
Button saveButton = new();
```
**Do NOT use target-typed `new()` when the type isn't visible on the same line:**
```csharp
// DO — type is visible on the right, so var is fine:
var map = new Dictionary<string, List<int>>();
// DON'T — _map is a backing field declared elsewhere,
// so the type isn't visible here. Too implicit.
_map = new();
```
6. **`var` is always fine for tuple deconstruction:**
```csharp
var (nodes, images) = viewModel.UpdateTreeView(displayStyle);
var (key, value) = dictionary.First();
```
7. Using Collection expressions:
```csharp
// Before
List<string> items = new List<string>();
// After
List<string> items = [];
```
* Consider collection expressions also for methods that return collections, e.g.:
```csharp
// Before
Control[] controls = _view.Controls.Cast<Control>().ToArray();
// After
Control[] controls = [.. _view.Controls.Cast<Control>()];
```
* Avoid, however, collection expressions, when constructable array/collection
type are necessary in the context, e.g.:
```csharp
// Be careful! Will not compile, we need a constructable array type in this
// context, so collection initializer syntax is not possible here.
Control CreateErrorControlForMessage(string message)
=> CreateErrorControl([new InvalidOperationException(message)]);
// In this case we need:
Control CreateErrorControlForMessage(string message)
=> CreateErrorControl(new[] { new InvalidOperationException(message) });
```
## Null Checking
* **Use `is null` / `is not null`** — never `== null` or `!= null`.
* Use coalesce: `value ?? "default"`, `value ??= GetDefault()`.
## Naming and Field Conventions
| Element | Convention |
|---|---|
| `private` / `internal` instance fields | `_camelCase` |
| `private static` fields | `s_camelCase` |
| `[ThreadStatic]` fields | `t_camelCase` |
| Constants | `PascalCase` |
| All other members | `PascalCase` |
* **Never** qualify with `this.` unless strictly necessary to resolve ambiguity.
* Declare accessibility modifiers **explicitly** on every type and member.
* Use the **narrowest possible scope** — prefer `private` over `internal` over
`public`.
* Mark members `static` when they do not access instance state.
## Formatting and Line Length
### Expression-bodied members
Use expression bodies (`=>`) for single-expression methods and read-only
properties. When the **total line length would exceed 60 characters**, wrap by
placing the `=>` on the next line, indented:
```csharp
// Short — fits on one line
internal int BorderWidth => _borderWidth;
// Long — wrap the arrow to the next line
private bool IsValidSize(Size size)
=> size.Width > 0 && size.Height > 0;
internal string QualifiedName
=> $"{Namespace}.{TypeName}";
```
> **Important semantic distinction:** `public Foo Bar => new Foo();` creates a
> new instance on every access. `public Foo Bar { get; } = new Foo();` creates
> one instance at construction. Never convert between these forms unless the
> original semantics were provably wrong.
### Braces and blocks
* **Allman style** — opening brace on its own line.
* Insert an **empty line** after closing braces of control-flow blocks and
**before `return` statements**.
* If a comment precedes a line that needs an empty line above it, the empty line
goes **before the comment**.
### Ternary operator
Put each branch on its own line unless the whole expression is very short:
```csharp
Color textColor = e.Item.Enabled
? GetDarkModeColor(e.TextColor)
: GetDarkModeColor(SystemColors.GrayText);
```
## Pattern Matching and Switch Expressions
Prefer `switch` expressions over `switch` statements over `if`-chains:
```csharp
string result = value switch
{
> 0 => "Positive",
< 0 => "Negative",
_ => "Zero"
};
```
Use `and`, `or`, relational, property, tuple, type, and list patterns where they
improve clarity. When converting `if`-chains that return or assign, a switch
expression is almost always clearer.
## Readability
1. **Never sacrifice readability for brevity**
Prefer extension method call syntax over static helpers when the same operation is available in both forms — extensions read more naturally and reduce visual noise:
```csharp
// Prefer
Size deviceSize = image.Size.LogicalToDeviceUnits();
// Over
Size deviceSize = DpiHelper.LogicalToDeviceUnits(image.Size);
```
2. **Prefer inline `#pragma` or `[SuppressMessage]`**
Use inline `#pragma` or `[SuppressMessage]` at the call site over global suppressions, so justification is visible in context.
3. **Named arguments**
Use named arguments when passing multiple literals or when the meaning of a parameter isn't clear from the argument expression itself:
```csharp
// GOOD — named arguments clarify meaning of literals
var errorControl = CreateErrorControlForMessage(
message: "An unexpected error occurred. Please try again.",
showRetryButton: true);
```
**Note:** When method calls take a lot of space due to a long argument list, consider wrapping the individual arguments on separate lines. If you then decide to use named arguments, use them for *every* argument to improve readability and consistency:
```csharp
LongMethodWithManyNamedArguments(
firstArgument: value1,
secondArgument: value2,
thirdArgument: value3,
fourthArgument: value4);
```
4. **Wrap dot-chains with more than 2 member accesses** — each call goes on its
own indented line:
```csharp
// Fine — 2 or fewer:
var names = items.Where(x => x.IsActive).ToList();
// Wrap — more than 2:
var results = collection
.Where(x => x.IsActive)
.OrderBy(x => x.Name)
.Select(x => x.Id)
.ToList();
```
## Error Handling and Argument Validation
Use **throw-helper methods** — never hand-roll null / range checks:
```csharp
ArgumentNullException.ThrowIfNull(parameter);
ArgumentOutOfRangeException.ThrowIfNegative(value);
ObjectDisposedException.ThrowIf(_disposed, this);
```
Always use `nameof()` for parameter and member names in exceptions and asserts.
## Performance Idioms
* Single-`char` overloads: `text.Contains('c')`, `sb.Append('x')`.
* `ReadOnlySpan<char>` over `Substring` when possible.
* `items.Any()` over `Count() > 0`.
* `TryGetValue` over `ContainsKey` + indexer.
* `string.IsNullOrEmpty` over `?.Length == 0`.
* `Array.Empty<T>()` over `new T[0]`.
* Prefer `using` declarations (`using var ...`) over `using` blocks. Use the
block form only when a tighter scope is required.
```csharp
using Pen focusPen = new(focusColor)
{
Width = 1.0f,
DashStyle = DashStyle.Dot
};
```
## Magic Numbers
Replace/avoid hard-coded literals with named constants or enums for new code when possible. If a literal is truly self-explanatory and unlikely to change, it may be acceptable to leave it as-is.
```csharp
## XML Documentation
Every class, struct, record, interface, and enum — **regardless of access
modifier, including `private` nested types** — must have an XML doc header:
* **`<summary>`** — always present; a concise statement of the type's purpose.
* **`<remarks>`** — add for non-trivial types. Use `<para>` for multiple
paragraphs.
* Use `<inheritdoc/>` on overridden members.
* Do **not** XML-comment local functions; use a regular `//` comment if
the purpose is not self-evident.
* Use **Unicode characters** in docs — never HTML entities.
* Indent XML structure with **1 space** per nesting level:
```csharp
/// <summary>
/// Gets or sets the border width of the control.
/// </summary>
/// <remarks>
/// <para>
/// The border width affects the visual appearance and layout
/// calculations of the control.
/// </para>
/// <para>
/// Values must be non-negative. A value of 0 means no border.
/// </para>
/// </remarks>
public int BorderWidth { get; set; }
```
## File Structure
* File-scoped namespaces.
* UTF-8 with BOM, CRLF line endings.
* 4-space indentation, no tabs.
* No trailing whitespace; final newline at end of file.
## WinForms-Specific
### Events
```csharp
public event EventHandler<EventArgs>? Click;
protected virtual void OnClick(EventArgs e)
{
Click?.Invoke(this, e);
}
// NRT-aware handler signature
private void OnSomeEvent(object? sender, EventArgs e) { }
```
Use `EventArgs.Empty` for parameterless event raises.
### Designer integration
* Mark designer-generated controls as nullable:
`private Button? _okButton;`
* Dispose components with `is not null`:
```csharp
protected override void Dispose(bool disposing)
{
if (disposing && components is not null)
{
components.Dispose();
}
base.Dispose(disposing);
}
```
### Platform attributes
```csharp
[SupportedOSPlatform("windows")]
private void WindowsSpecificMethod() { }
```
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · dotnet/winforms | 100 | MIT |
| zereight/gitlab-mcp | 100 | MIT |
| shinpr/ai-coding-project-boilerplate | 100 | MIT |
| adelrodriguez/skills | 100 | MIT |
| nokri-mohammed/claude-team | 100 | MIT |
| MARUCIE/openclaw-foundry | 100 | MIT |
| kid-sid/codex-spellbook | 100 | MIT |
| shinpr/ai-coding-project-boilerplate | 96 | MIT |
| affaan-m/ECC | 95 | MIT |
Database snapshot: 13.11.2026 · package version d1fbfb45cc4d (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 95csharp-style
Applies C# coding conventions when writing, reviewing, or refactoring code. Covers .cs files, XML documentation, naming, formatting, error handling, using directives, file ordering, and Unity-specific patterns. Use when writing new C# code, modifying existing code, reviewing… - 100go-coding-standards
Go coding standards and style conventions grounded in Effective Go, Go Code Review Comments, and production-proven idioms. Use when writing or reviewing Go code for import ordering, variable declarations, struct initialization, nesting, receivers, struct tags, or formatting… - 100csharp-conventions
General C# coding conventions covering latest language features (C# 13), nullable reference types, naming conventions, formatting rules, exception handling, project structure, data access patterns, validation, and structured logging. Apply this skill whenever writing, reviewing,… - 100code-standards
C# naming conventions, member ordering, formatting rules, nullable reference types, memory/GC rules, test patterns, and PR standards. Use when writing, reviewing, or modifying non-trivial C# changes in this Unity project — applies to ECS systems, controllers, tests, utilities, and plugins. - 95python-style
Applies Python coding conventions when writing, reviewing, or refactoring code. Covers .py files, docstrings, type annotations, naming, formatting, error handling, imports, file ordering, and ataraxis library preferences. Use when writing new Python code, modifying existing… - 93download-sdk
Instructions for downloading and installing .NET preview runtime versions required by the WinForms repository. Use when test executables fail with "framework not found" errors or when a specific .NET preview runtime version needs to be installed.