PowerToys 编码风格指南clang-format、XamlStyler 与多语言格式化的落地实践【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys本文基于 PowerToys 仓库的开发者风格文档 doc/devdocs/development/style.md 展开系统讲解该仓库在多语言代码库C / C# / XAML中如何统一编码风格包括存量代码跟随旧风格、新增代码向 Modern C 靠拢的哲学原则clang-format 风格文件的逐项解读format_sources.ps1批量格式化脚本的工作原理XamlStyler 对 XAML 文件的属性排序与换行规则以及 .NET 侧通过 StyleCop.json 与 .editorconfig 落地风格约束的配套实践。读完后你将能够在新贡献代码时正确选择格式化入口并理解每一项风格配置背后的实现依据。风格哲学存量跟随、增量现代化文档 doc/devdocs/development/style.md 开篇给出了两条最基本的原则向既有类/函数中插入代码时尽量贴近该文件、该类的现有风格保持一致性是首要目标全新代码或对整个类/区域做重构时尽可能采用 Modern C 风格并以 C Core Guidelinesisocpp 的 C 核心指南作为参照。这条双轨制原则对大型多语言仓库非常实用它避免了一次性重排整个代码库带来的巨大 diff 噪音同时保证新增代码逐步向现代风格收敛。这也与文档结尾的说明相呼应——CI 目前并不强制检查代码格式因为格式化是逐步应用到代码库的渐进过程但任何新代码都必须遵循仓库的格式化风格。C 格式化仓库级 .clang-format 风格文件PowerToys 使用 clang-format 做 C/C 的自动格式化仓库中的风格文件位于 src/.clang-format。下面选取该文件中最具代表性、也最能解释仓库代码为什么长这样的配置项进行解读配置项取值含义IndentWidth/TabWidth4缩进 4 空格UseTab: Never禁止使用 TabColumnLimit0不强制换行列宽由格式化器按语法结构折行BreakBeforeBracesCustom使用自定义花括号位置由BraceWrapping细分控制BraceWrapping.After*Class/Function/Namespace/Enum 等true类、函数、命名空间、枚举等关键字后强制换行Allman 风格NamespaceIndentationAll命名空间内部所有成员整体再缩进一级AccessModifierOffset-4public:等访问说明符相对类名反向缩进 4PointerAlignmentLeft指针星号靠左如int* pIncludeBlocksRegroup按IncludeCategories优先级对#include重新分组SortUsingDeclarationstrue命名空间 using 声明自动排序MaxEmptyLinesToKeep1最多保留 1 行连续空行ForEachMacrosTEST_CLASS、TEST_METHOD让 clang-format 把 GoogleTest 宏块当作可缩进的结构MacroBlockBegin/MacroBlockEndBEGIN_TEST_METHOD\|END_TEST_METHOD等将BEGIN_MODULE等成对宏块按块缩进StandardCpp11按 C11 语义解析其中IncludeCategories定义了头文件引入的分组优先级-1匹配precomp|pch|stdafx预编译头永远排第一1匹配双引号头文件2匹配尖括号系统头3为兜底分组——这解释了仓库中本项目头文件在前、系统头在后的包含顺序。ForEachMacros与MacroBlockBegin/End则是专为 GoogleTest 用例缩进服务的细节保证TEST_CLASS/BEGIN_TEST_METHOD块内的语句正确缩进。仓库内 C 测试框架的用法可以在src/common/UnitTests-CommonUtils、src/runner/UnitTests等目录中找到实例这些目录中的BEGIN_TEST_METHOD宏块正是依赖上述配置来格式化。命令行格式化format_sources.ps1 的工作机制文档给出了一条不依赖 IDE 的格式化入口从命令行执行 format_sources 脚本。阅读 src/codeAnalysis/format_sources.ps1 源码可以看到它的完整行为1. 解析 clang-format 可执行文件第 9–16 行$clangFormat clang-format.exe if(!(Get-Command $clangFormat -ErrorAction SilentlyContinue)) { Write-Information Cant find clang-format.exe in %PATH%, trying to use %VCINSTALLDIR%... $clangFormat$env:VCINSTALLDIR\Tools\Llvm\bin\clang-format.exe ... }脚本优先在%PATH%中查找clang-format.exe找不到时会回退到 Visual Studio 自带的 LLVM 工具链目录%VCINSTALLDIR%\Tools\Llvm\bin\。这就是文档中若从Native Tools Command Prompt for VS启动脚本它可以在 PATH 之外推断出 VS 附带的 clang-format 路径的实现来源——该回退依赖vcvars.bat设置的VCINSTALLDIR环境变量。2. 计算待格式化文件集合第 22–47 行默认模式Get-Dirty-Files-From-Git函数合并三路 git 状态——git diff --name-only --diff-filterd --cached已暂存、git ls-files -m工作区已修改、git ls-files --others --exclude-standard未跟踪新文件再按扩展名过滤。脚本只会处理.cpp和.h第 18–20 行其余文件不受影响-all模式递归遍历..\src目录下的全部.cpp/.h并排除Generated Files与node_modules目录适合一次性对整棵源码树做格式化。3. 逐个文件执行格式化第 49–52 行 $clangFormat -i -stylefile -fallback-stylenone $_-stylefile让 clang-format 自动向上查找并使用 src/.clang-format-fallback-stylenone确保找不到风格文件时不做任何猜测性格式化。需要说明cmdpal 模块内另有一份同名脚本 src/modules/cmdpal/format_sources.ps1逻辑与主脚本一致服务于该模块独立的历史目录结构。C# 风格约束StyleCop.json 与 .editorconfig虽然 style.md 主要面向 C/XAML但从源码结构看PowerToys 的 .NET 侧launcher、settings-ui 等大量 C# 代码风格约束由两个仓库级文件承载1. src/codeAnalysis/StyleCop.json配置了 StyleCop 分析器的全局行为关键项包括documentationRules.copyrightText规定所有文件的版权声明模板Copyright (c) Microsoft CorporationMIT 许可xmlHeader: false表示不强制 XML 文档头layoutRules.newlineAtEndOfFile: require文件末尾必须有换行符orderingRulesusing指令置于命名空间之外且System命名空间优先。2. src/.editorconfig则把风格细化到了 IDE 可用的诊断级别代表性规则有file_header_template与 StyleCop 相同的版权文件头模板适用于[*.cs]csharp_style_prefer_braces true强制大括号csharp_style_namespace_declarations block_scoped使用块级命名空间声明dotnet_naming_rule.interface_should_be_begins_with_i接口必须以I开头且使用 PascalCasecsharp_indent_labels one_less_than_currentcase标签相对switch减一级缩进tab_width 4、indent_size 4、end_of_line crlf与 C 侧的 4 空格缩进保持一致的换行与缩进约定大量IDE####系列规则如IDE0031使用空值传播、IDE0044加readonly修饰符、IDE0029简化空值检查被设为suggestion级别作为 IDE 建议而非硬错误。这些配置使 C# 部分的风格检查融入日常 IDE 编码过程与 C 侧 clang-format 的保存/提交前格式化形成互补。XAML 格式化XamlStyler 与 applyXamlStyling.ps1PowerToys 使用 Xavalon 的 XamlStyler 工具统一 XAML 文件风格。文档给出的本地执行方式为.\.pipelines\applyXamlStyling.ps1 -Main也可以安装 XamlStyler 的 Visual Studio 扩展在 IDE 内格式化。仓库中的实际实现是 .pipelines/applyXamlStyling.ps1其行为比文档描述更完整1. 五种运行范围第 31–37 行参数开关行为无参数默认基于git status -s --porcelain只处理当前未提交的新增/修改文件-Unstagedgit diff --name-only --diff-filterACM只看未暂存改动-Stagedgit diff --cached只看已暂存文件-LastCommitgit diff HEAD^ HEAD对照上一次提交-Maingit diff origin/main branch对照 main 分支全量差异-Passive被动检查全仓所有 XAMLCI 场景不修改文件仅按退出码报错2. 文件筛选与排除脚本用正则\.xaml$只挑 XAML 文件并通过$PathExcludes排除obj、bin、x64、Generated Files\PowerRenameXAML、RegistryPreviewUILib\Controls\HexBox等生成或第三方目录第 45 行。3. 实际调用dotnet tool run xstyler -c $PSScriptRoot\..\src\Settings.XamlStyler -f $files风格定义文件是 src/Settings.XamlStyler-Passive模式追加-p只检查不修改。该 JSON 配置的核心规则包括MaxAttributesPerLine: 1每个属性独占一行NewlineExemptionElements列出的GradientStop、ScaleTransform等短元素除外可写在单行内EnableAttributeReordering: true配合AttributeOrderingRuleGroups按x:Class→xmlns→x:Key/x:Name/Title→Grid.Row/Column等布局属性 →Width/Height系 →Margin/Padding/对齐→ 通配属性 的固定顺序重排属性RemoveEndingTagOfEmptyElement: true空元素使用自闭合写法SpaceBeforeClosingSlash: true自闭合标签写为/而非/前无空格的紧凑写法之外的形式ReorderVSM: 2对 VisualStateManager 的 State 列表做规范化重排ThicknessSeparator: 2及ThicknessAttributes统一Margin、Padding、BorderThickness等厚度属性的分隔符风格。这套规则保证了 settings-ui、launcher 等大量 WinUI 3 XAML 页面在属性顺序与换行上的一致性。CI 现状与对新代码的约定文档最后明确由于格式化是渐进推行的CI 尚未强制检查代码格式但所有新代码必须遵循上述格式化约定。结合仓库实现可以归纳出贡献者应当遵循的完整流程C 新文件/改动确保在%PATH%或 VS Native Tools 命令行中可用 clang-formatIDE 内使用CTRLK CTRLD格式化当前文档或命令行运行src\codeAnalysis\format_sources.ps1批量处理 git 脏文件XAML 改动提交前运行.\.pipelines\applyXamlStyling.ps1默认只查未提交文件或-Main对照 main 全量修复C# 代码遵循 src/.editorconfig 的命名与 IDE 规则建议文件头版权模板与文件末尾换行要求由 src/codeAnalysis/StyleCop.json 定义风格基准存量修改跟随原文件风格新代码向 Modern C参照 C Core Guidelines收敛。相关文件索引用途路径风格哲学与工具入口本文主体文档doc/devdocs/development/style.mdclang-format 仓库级风格文件src/.clang-formatC 批量格式化脚本src/codeAnalysis/format_sources.ps1cmdpal 模块的格式化脚本副本src/modules/cmdpal/format_sources.ps1XAML 格式化流水线脚本.pipelines/applyXamlStyling.ps1XamlStyler 风格定义src/Settings.XamlStylerC# StyleCop 分析器配置src/codeAnalysis/StyleCop.jsonC#/.NET 代码风格与命名规则src/.editorconfig【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PowerToys 编码风格指南：clang-format、XamlStyler 与多语言格式化的落地实践
PowerToys 编码风格指南clang-format、XamlStyler 与多语言格式化的落地实践【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys本文基于 PowerToys 仓库的开发者风格文档 doc/devdocs/development/style.md 展开系统讲解该仓库在多语言代码库C / C# / XAML中如何统一编码风格包括存量代码跟随旧风格、新增代码向 Modern C 靠拢的哲学原则clang-format 风格文件的逐项解读format_sources.ps1批量格式化脚本的工作原理XamlStyler 对 XAML 文件的属性排序与换行规则以及 .NET 侧通过 StyleCop.json 与 .editorconfig 落地风格约束的配套实践。读完后你将能够在新贡献代码时正确选择格式化入口并理解每一项风格配置背后的实现依据。风格哲学存量跟随、增量现代化文档 doc/devdocs/development/style.md 开篇给出了两条最基本的原则向既有类/函数中插入代码时尽量贴近该文件、该类的现有风格保持一致性是首要目标全新代码或对整个类/区域做重构时尽可能采用 Modern C 风格并以 C Core Guidelinesisocpp 的 C 核心指南作为参照。这条双轨制原则对大型多语言仓库非常实用它避免了一次性重排整个代码库带来的巨大 diff 噪音同时保证新增代码逐步向现代风格收敛。这也与文档结尾的说明相呼应——CI 目前并不强制检查代码格式因为格式化是逐步应用到代码库的渐进过程但任何新代码都必须遵循仓库的格式化风格。C 格式化仓库级 .clang-format 风格文件PowerToys 使用 clang-format 做 C/C 的自动格式化仓库中的风格文件位于 src/.clang-format。下面选取该文件中最具代表性、也最能解释仓库代码为什么长这样的配置项进行解读配置项取值含义IndentWidth/TabWidth4缩进 4 空格UseTab: Never禁止使用 TabColumnLimit0不强制换行列宽由格式化器按语法结构折行BreakBeforeBracesCustom使用自定义花括号位置由BraceWrapping细分控制BraceWrapping.After*Class/Function/Namespace/Enum 等true类、函数、命名空间、枚举等关键字后强制换行Allman 风格NamespaceIndentationAll命名空间内部所有成员整体再缩进一级AccessModifierOffset-4public:等访问说明符相对类名反向缩进 4PointerAlignmentLeft指针星号靠左如int* pIncludeBlocksRegroup按IncludeCategories优先级对#include重新分组SortUsingDeclarationstrue命名空间 using 声明自动排序MaxEmptyLinesToKeep1最多保留 1 行连续空行ForEachMacrosTEST_CLASS、TEST_METHOD让 clang-format 把 GoogleTest 宏块当作可缩进的结构MacroBlockBegin/MacroBlockEndBEGIN_TEST_METHOD\|END_TEST_METHOD等将BEGIN_MODULE等成对宏块按块缩进StandardCpp11按 C11 语义解析其中IncludeCategories定义了头文件引入的分组优先级-1匹配precomp|pch|stdafx预编译头永远排第一1匹配双引号头文件2匹配尖括号系统头3为兜底分组——这解释了仓库中本项目头文件在前、系统头在后的包含顺序。ForEachMacros与MacroBlockBegin/End则是专为 GoogleTest 用例缩进服务的细节保证TEST_CLASS/BEGIN_TEST_METHOD块内的语句正确缩进。仓库内 C 测试框架的用法可以在src/common/UnitTests-CommonUtils、src/runner/UnitTests等目录中找到实例这些目录中的BEGIN_TEST_METHOD宏块正是依赖上述配置来格式化。命令行格式化format_sources.ps1 的工作机制文档给出了一条不依赖 IDE 的格式化入口从命令行执行 format_sources 脚本。阅读 src/codeAnalysis/format_sources.ps1 源码可以看到它的完整行为1. 解析 clang-format 可执行文件第 9–16 行$clangFormat clang-format.exe if(!(Get-Command $clangFormat -ErrorAction SilentlyContinue)) { Write-Information Cant find clang-format.exe in %PATH%, trying to use %VCINSTALLDIR%... $clangFormat$env:VCINSTALLDIR\Tools\Llvm\bin\clang-format.exe ... }脚本优先在%PATH%中查找clang-format.exe找不到时会回退到 Visual Studio 自带的 LLVM 工具链目录%VCINSTALLDIR%\Tools\Llvm\bin\。这就是文档中若从Native Tools Command Prompt for VS启动脚本它可以在 PATH 之外推断出 VS 附带的 clang-format 路径的实现来源——该回退依赖vcvars.bat设置的VCINSTALLDIR环境变量。2. 计算待格式化文件集合第 22–47 行默认模式Get-Dirty-Files-From-Git函数合并三路 git 状态——git diff --name-only --diff-filterd --cached已暂存、git ls-files -m工作区已修改、git ls-files --others --exclude-standard未跟踪新文件再按扩展名过滤。脚本只会处理.cpp和.h第 18–20 行其余文件不受影响-all模式递归遍历..\src目录下的全部.cpp/.h并排除Generated Files与node_modules目录适合一次性对整棵源码树做格式化。3. 逐个文件执行格式化第 49–52 行 $clangFormat -i -stylefile -fallback-stylenone $_-stylefile让 clang-format 自动向上查找并使用 src/.clang-format-fallback-stylenone确保找不到风格文件时不做任何猜测性格式化。需要说明cmdpal 模块内另有一份同名脚本 src/modules/cmdpal/format_sources.ps1逻辑与主脚本一致服务于该模块独立的历史目录结构。C# 风格约束StyleCop.json 与 .editorconfig虽然 style.md 主要面向 C/XAML但从源码结构看PowerToys 的 .NET 侧launcher、settings-ui 等大量 C# 代码风格约束由两个仓库级文件承载1. src/codeAnalysis/StyleCop.json配置了 StyleCop 分析器的全局行为关键项包括documentationRules.copyrightText规定所有文件的版权声明模板Copyright (c) Microsoft CorporationMIT 许可xmlHeader: false表示不强制 XML 文档头layoutRules.newlineAtEndOfFile: require文件末尾必须有换行符orderingRulesusing指令置于命名空间之外且System命名空间优先。2. src/.editorconfig则把风格细化到了 IDE 可用的诊断级别代表性规则有file_header_template与 StyleCop 相同的版权文件头模板适用于[*.cs]csharp_style_prefer_braces true强制大括号csharp_style_namespace_declarations block_scoped使用块级命名空间声明dotnet_naming_rule.interface_should_be_begins_with_i接口必须以I开头且使用 PascalCasecsharp_indent_labels one_less_than_currentcase标签相对switch减一级缩进tab_width 4、indent_size 4、end_of_line crlf与 C 侧的 4 空格缩进保持一致的换行与缩进约定大量IDE####系列规则如IDE0031使用空值传播、IDE0044加readonly修饰符、IDE0029简化空值检查被设为suggestion级别作为 IDE 建议而非硬错误。这些配置使 C# 部分的风格检查融入日常 IDE 编码过程与 C 侧 clang-format 的保存/提交前格式化形成互补。XAML 格式化XamlStyler 与 applyXamlStyling.ps1PowerToys 使用 Xavalon 的 XamlStyler 工具统一 XAML 文件风格。文档给出的本地执行方式为.\.pipelines\applyXamlStyling.ps1 -Main也可以安装 XamlStyler 的 Visual Studio 扩展在 IDE 内格式化。仓库中的实际实现是 .pipelines/applyXamlStyling.ps1其行为比文档描述更完整1. 五种运行范围第 31–37 行参数开关行为无参数默认基于git status -s --porcelain只处理当前未提交的新增/修改文件-Unstagedgit diff --name-only --diff-filterACM只看未暂存改动-Stagedgit diff --cached只看已暂存文件-LastCommitgit diff HEAD^ HEAD对照上一次提交-Maingit diff origin/main branch对照 main 分支全量差异-Passive被动检查全仓所有 XAMLCI 场景不修改文件仅按退出码报错2. 文件筛选与排除脚本用正则\.xaml$只挑 XAML 文件并通过$PathExcludes排除obj、bin、x64、Generated Files\PowerRenameXAML、RegistryPreviewUILib\Controls\HexBox等生成或第三方目录第 45 行。3. 实际调用dotnet tool run xstyler -c $PSScriptRoot\..\src\Settings.XamlStyler -f $files风格定义文件是 src/Settings.XamlStyler-Passive模式追加-p只检查不修改。该 JSON 配置的核心规则包括MaxAttributesPerLine: 1每个属性独占一行NewlineExemptionElements列出的GradientStop、ScaleTransform等短元素除外可写在单行内EnableAttributeReordering: true配合AttributeOrderingRuleGroups按x:Class→xmlns→x:Key/x:Name/Title→Grid.Row/Column等布局属性 →Width/Height系 →Margin/Padding/对齐→ 通配属性 的固定顺序重排属性RemoveEndingTagOfEmptyElement: true空元素使用自闭合写法SpaceBeforeClosingSlash: true自闭合标签写为/而非/前无空格的紧凑写法之外的形式ReorderVSM: 2对 VisualStateManager 的 State 列表做规范化重排ThicknessSeparator: 2及ThicknessAttributes统一Margin、Padding、BorderThickness等厚度属性的分隔符风格。这套规则保证了 settings-ui、launcher 等大量 WinUI 3 XAML 页面在属性顺序与换行上的一致性。CI 现状与对新代码的约定文档最后明确由于格式化是渐进推行的CI 尚未强制检查代码格式但所有新代码必须遵循上述格式化约定。结合仓库实现可以归纳出贡献者应当遵循的完整流程C 新文件/改动确保在%PATH%或 VS Native Tools 命令行中可用 clang-formatIDE 内使用CTRLK CTRLD格式化当前文档或命令行运行src\codeAnalysis\format_sources.ps1批量处理 git 脏文件XAML 改动提交前运行.\.pipelines\applyXamlStyling.ps1默认只查未提交文件或-Main对照 main 全量修复C# 代码遵循 src/.editorconfig 的命名与 IDE 规则建议文件头版权模板与文件末尾换行要求由 src/codeAnalysis/StyleCop.json 定义风格基准存量修改跟随原文件风格新代码向 Modern C参照 C Core Guidelines收敛。相关文件索引用途路径风格哲学与工具入口本文主体文档doc/devdocs/development/style.mdclang-format 仓库级风格文件src/.clang-formatC 批量格式化脚本src/codeAnalysis/format_sources.ps1cmdpal 模块的格式化脚本副本src/modules/cmdpal/format_sources.ps1XAML 格式化流水线脚本.pipelines/applyXamlStyling.ps1XamlStyler 风格定义src/Settings.XamlStylerC# StyleCop 分析器配置src/codeAnalysis/StyleCop.jsonC#/.NET 代码风格与命名规则src/.editorconfig【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考