Coding Standards

本节定义最小但关键的编码规范，专注于项目特定的规则，防止常见错误。这些规范将被开发者和 AI Agent 遵循。

Critical Rules

以下规则是强制性的，违反将导致代码审查不通过：

命名空间组织： 所有控件必须放在 Penguin.AvaloniaUI.Controls.* 命名空间下，布局控件在 Penguin.AvaloniaUI.Layouts，主题在 Penguin.AvaloniaUI.Themes。不得跨命名空间引用内部实现细节。
依赖属性定义： 所有公开的可绑定属性必须定义为 StyledProperty，使用 AvaloniaProperty.Register<> 注册，不得使用字段或普通属性。
XAML 资源引用： 所有颜色、字体、间距必须从主题资源字典引用，禁止硬编码颜色值（如 #FFFFFF）。使用 {DynamicResource TextPrimary} 而非 {StaticResource}，确保主题切换生效。
ReactiveUI 集成： ViewModel 必须继承 ReactiveObject，属性变化使用 this.RaiseAndSetIfChanged(ref _field, value)，不得直接触发 PropertyChanged 事件。
错误处理： 公开 API 方法必须验证参数（如 ArgumentNullException），内部方法可使用 Debug.Assert。不得吞没异常（空 catch 块）。

XML 文档注释： 所有 public 和 protected 成员必须有 XML 注释（///），包括 <summary>、<param>、<returns>。示例：

/// <summary>
/// 应用指定的主题类型
/// </summary>
/// <param name="type">主题类型（Light 或 Dark）</param>
public static void ApplyTheme(ThemeType type)

禁止反射动态创建控件： PropertyGrid 可以使用反射解析属性，但不得使用 Activator.CreateInstance 动态创建编辑器控件。使用工厂模式或字典映射。
主题资源命名约定： 语义化颜色必须使用统一前缀：TextPrimary、TextSecondary、BackgroundPrimary、SurfaceElevated。不得使用 Color1、MyBlue 等非语义化命名。
API查询规则： 在使用不熟悉的API的时候，优先使用 mcp-context7 进行上下文查找。

Naming Conventions

元素类型	命名规则	示例
控件类	PascalCase，功能名称 + 控件类型后缀（可选）	`PropertyGrid`, `TwoColumnLayout`
依赖属性	PascalCase，属性名 +`Property` 后缀	`SelectedObjectProperty`
私有字段	camelCase，下划线前缀	`_currentTheme`
事件	PascalCase，动词过去式	`ThemeChanged`, `PropertyValueChanged`
方法	PascalCase，动词开头	`ApplyTheme()`, `RefreshProperties()`
XAML 文件	PascalCase，与类名一致	`PropertyGrid.axaml`
测试方法	PascalCase，MethodName_Scenario_ExpectedResult	`ApplyTheme_WithDarkTheme_ShouldUpdateResources()`

File Organization Rules

一个文件一个类：每个控件类单独一个 .cs 文件，不得在同一文件中定义多个公开类（嵌套私有类除外）。
XAML 与代码分离：控件的 XAML 模板放在 Themes/ 子目录下，与类定义分离：
```
Controls/PropertyGrid/PropertyGrid.cs
Controls/PropertyGrid/Themes/PropertyGrid.axaml
```
数据模型独立文件：数据模型类（如 PropertyItem, GuideStep）与控件类分离，放在同级目录下。

文件格式规范：命名空间单独放在文件顶部，减少缩进层级：

namespace Penguin.AvaloniaUI.Controls;

public class PropertyGrid : TemplatedControl
{
    // 类实现
}

Code Style (基于 .editorconfig)

项目使用 .editorconfig 强制执行以下规则：

root = true

[*.cs]
indent_style = space
indent_size = 4
end_of_line = crlf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

# C# 规则
csharp_new_line_before_open_brace = all
csharp_prefer_braces = true:warning
csharp_style_var_for_built_in_types = true:suggestion
csharp_style_var_when_type_is_apparent = true:suggestion

[*.axaml]
indent_size = 2

代码风格要点：

使用 var 声明局部变量（如 var count = 100;）
命名空间单独一行，不使用文件范围命名空间的花括号嵌套

运行格式化检查：

dotnet format --verify-no-changes

4.7 KiB Raw Blame History Unescape Escape

Coding Standards

Critical Rules

Naming Conventions

File Organization Rules

Code Style (基于 .editorconfig)

4.7 KiB

Raw Blame History