Coding Style

TLDR

• Naming Rules: Except for variables using camelCase, most members use PascalCase; fields do not use prefixes; interfaces start with 'I'; abbreviation rules follow word count and casing conventions.
• Ordering Rules: Follow StyleCop (SA12xx) standards, with priority given to access modifiers, static, readonly, etc.; using declarations must be sorted by System. prefix, alphabetical order, and alias classification.
• Commenting Style: Lean towards Clean Code style; comments should explain "why" rather than "what"; use // for single-line comments; public APIs must use XML documentation comments; use keywords like TODO and HACK to mark tasks.
• Formatting Rules: Use K&R style (opening brace on the same line); when breaking lines for operators, binary operators should be placed at the beginning of the new line; ternary operators should be broken across lines if too long to maintain readability; a blank line should be preserved at the end of the file.

Naming Rules

In C# naming conventions, casing formats should be chosen based on member type, and obsolete prefixes should be avoided.

• Casing Conventions: Except for variables using camelCase, most members (such as methods and classes) use PascalCase.
• Field Naming:
  • Public and internal fields use PascalCase.
  • Constants and static readonly fields use PascalCase.
  • Other fields use camelCase and do not require prefixes such as "", "m", or "s_".
• Interfaces and Generics: Interface names must start with "I"; if a generic parameter is single and arbitrary, "T" is sufficient.
• Abbreviation Handling:
  • For abbreviations of three or more words (e.g., Sql), only the first letter is capitalized.
  • For abbreviations of two words (e.g., Id), only the first letter is capitalized.
  • For acronyms of two words (e.g., IO), use all uppercase or all lowercase.

Ordering Rules

Code ordering should follow StyleCop (SA12xx) standards to ensure structural consistency.

• Member Ordering: Sort based on access modifiers (public > internal > protected > private).
• Keyword Ordering: Constant fields must come before non-constant fields; static must be placed above non-static; readonly fields must be placed before non-readonly fields.
• Using Ordering:
  • Priority: Using Namespaces > Using Static > Using Alias.
  • Within Namespaces: System. comes first, followed by others in alphabetical order.
• Method Ordering Suggestion: Do not strictly adhere to access modifiers; it is recommended to group methods with high homogeneity or calling relationships together to facilitate reading.

Complete Example

The following is an example of the recommended code structure:

using Namespace;
using static Namespace.StaticClassName;
using Namespace = Alias;

public class ClassName {
    #region Fields
    public const int ConstantName = 0;
    public readonly static int ReadonlyStaticFieldName = 0;
    private static int StaticFieldName = 0;
    private int fieldName = 0;
    #endregion

    public int PropertyName { get; set; }

    public void MethodName() {
        MethodA();
    }

    private void MethodA() { }
}

Comments

Comments should be purposeful and avoid redundant explanations.

• Single-line Comments: Use // followed by a space. Lean towards explaining "why this is being done" rather than recording "what the code is doing."
• Documentation Comments: Public classes, structs, interfaces, or members should use XML documentation comments. If generics need to be marked, use {} instead of <> to avoid XML parsing errors.
• Task List: Use built-in Visual Studio keywords to manage tasks:
  • TODO: Mark features that need to be completed in the future.
  • UNDONE: Mark work that is in progress but not yet finished.
  • HACK: Mark temporary solutions that need to be fixed as soon as possible.

Formatting

Formatting rules are intended to improve code readability and consistency.

• Opening Braces: Use the same-line style (e.g., if () {).
• Spacing: Add spaces after commas, after control flow keywords, and around operators (except ++ and --).
• Operator Line Breaks: Use "out-of-line style"; binary operators (such as +, ||) should be placed at the beginning of the new line when breaking to facilitate visual separation.
• Ternary Operators: Nested ternary operators must be broken across lines; it is recommended to align sub-conditions to improve readability.
• End of File: A blank line should be preserved at the end of the file to comply with Unix/Linux newline conventions and prevent editor display anomalies.

TIP

It is recommended to keep code length within 80 to 120 characters; breaking lines appropriately avoids frequent scrolling on small screens and improves the development experience.

---

Change Log

• 2022-11-06 Initial version created.