简介这是一份面向C#开发人员及编程初学者的编码规范文档旨在统一团队代码风格、提升可读性与可维护性降低项目后期维护成本。PDF共1个文件约30KB篇幅精简便于快速查阅内容按引言、基本要求、用户界面设计原则、源程序书写规范、语句格式规范、命名规范等章节组织。文档对缩进与边距、大括号对齐、注释写法、括号与关键字使用、函数与变量声明等细节给出明确约定并单列函数命名、形参、常量与变量、接口与NameSpace、控件、类型、文件与文件夹等命名规则还包含源程序文档注释规范。读者可据此对照检查自身代码建立从代码排版到命名的一致标准也可作为团队内部规范宣讲与新人培训的参考材料。目前已有453人学习下载适合希望规范编程习惯、提升协作效率的开发者参考使用。1. 从一份 PDF 到一条流水线软件开发编码规范为什么总在落地时失效季度评审会上有人翻出那份《软件开发编码规范.pdf》指着第 4.3 节说这里明确要求所有对外接口必须做参数校验。会议室安静两秒然后有人问那线上那个空指针是怎么进去的答案往往很朴素——这份规范从发布那天起就没被任何工具读过它躺在共享盘里靠人的记忆运行而记忆在交付压力面前是最先被牺牲的东西。真正让编码规范产生价值的分水岭不在于条款写得多完整而在于有没有把它拆成三类东西机器能直接判定的格式、命名、圈复杂度、导入顺序、机器只能提示的注释完整性、死代码、复杂度趋势、只能靠人评审的领域命名是否达意、设计意图是否清晰。前两类必须沉到 linter 和流水线里第三类才留给 Code Review。这篇内容讲的就是这条拆解路径条款怎么分类、工具怎么选、参数怎么设、存量代码怎么逐步收口以及一份 PDF 如何演进成一个有版本、有指标、能被验证的规范体系。2. 把编码规范拆成可执行规则从文档条款到 linter 配置2.1 条款三分类能自动判定的才叫规范其余叫建议一份写得再厚的《软件开发编码规范.pdf》里面的条款其实只有六种形态。分不清这一点后面的工具选型全是碰运气。我一般先做一张映射表把每条条款打上标签再决定它是进流水线还是进评审清单。条款类型PDF 里的典型写法落地手段是否阻断合入格式类缩进 4 空格、行宽 120、文件末尾留空行EditorConfig、Prettier、clang-format是结构类函数不超过 80 行、圈复杂度不超过 15ESLint complexity、Ruff C901、PMD是命名类类名大驼峰、常量全大写下划线命名规则pep8-naming、id-match是文档类公共接口必须有 docstringpydocstyle、eslint-plugin-jsdoc视团队阶段架构类领域层不得依赖框架、禁止跨层调用ArchUnit、import-linter、依赖分析是意图类命名要达意、注释解释为什么这么写只能人工评审否表格右边那列就是分界线。凡是能写成一条规则的就不要留给评审凡是写不成规则的硬塞进评审只会让评审会变成格式辩论赛。很多团队的评审效率低根源就是把格式类条款也拿去讨论一个缩进能来回三轮。2.2 EditorConfig 与 Prettier格式类条款的最低成本配置格式类条款最忌讳两件事一是靠文档描述二是让 formatter 和 linter 同时管同一件事。前者没人执行后者会陷入改来改去的死循环。我的做法是先用 EditorConfig 统一编辑器行为再用 formatter 统一输出。# .editorconfig —— 编辑器层协议VSCode/JetBrains/Vim 原生或插件支持 root true [*] charset utf-8 end_of_line lf insert_final_newline true trim_trailing_whitespace true indent_style space indent_size 4 # 前端与配置文件跟社区习惯保持一致减少跨项目切换成本 [*.{js,ts,jsx,tsx,json,yml,yaml}] indent_size 2 # markdown 用行尾双空格表示换行不能裁掉 [*.md] trim_trailing_whitespace false// .prettierrc —— 只保留团队真的会争论的那几项 { printWidth: 120, semi: true, singleQuote: true, trailingComma: all, arrowParens: always, endOfLine: lf }printWidth设 120 而不是社区默认的 80是因为现在的屏幕宽度和中文注释的实际阅读体验80 会让稍微复杂一点的表达式被拆成七八行。trim_trailing_whitespace在 markdown 里必须关掉否则每次提交都会把有意义的换行删掉渲染出来的文档结构就散了。endOfLine统一成 lf 是跨平台协作的底线Windows 同事的 CRLF 会让 diff 整文件飘红。2.3 语义类条款怎么映射到具体工具不同技术栈的工具链差异很大这张表是我在多个项目里沉淀下来的默认选型微调空间主要在复杂度和重复度检测上。语言格式化静态检查复杂度/重复度JavaScript/TypeScriptPrettierESLint typescript-eslintESLint complexity、jscpdJavaSpotless google-java-formatCheckstyle、PMD、SpotBugsPMD CyclomaticComplexityPythonRuff formatRuff、PylintRuff C901、radonC/Cclang-formatclang-tidy、cppchecklizardC#dotnet formatRoslyn AnalyzersSonarQubeSQLsqlfluffsqlfluff一般不开嵌入式软件开发方向的 C 项目通常还要叠一层行业规范汽车电子常和 ASPICE 软件开发流程一起要求工具链一般是 clang-format 加 cppcheck 再加 MISRA 检查器的组合其中 MISRA 的很多条款本身就带豁免机制正好对上前面的例外流程。// eslint.config.js —— 把 PDF 里的结构类条款翻译成数字 export default [ { rules: { // 对应规范第 5.2 节函数圈复杂度不超过 15 complexity: [error, 15], // 对应规范第 5.3 节函数不超过 80 行空行和注释不计入 max-lines-per-function: [ error, { max: 80, skipBlankLines: true, skipComments: true }, ], // 对应规范第 3.1 节禁止使用 var no-var: error, // 对应规范第 3.5 节禁止直接打印统一走 logger no-console: [error, { allow: [warn, error] }], // 对应规范第 6.1 节禁止显式 any降一级为告警避免历史包袱卡死 typescript-eslint/no-explicit-any: warn, }, }, ];complexity的阈值不是拍脑袋定的先跑一遍全仓统计看中位数再取中位数上浮 20%这样大部分现有函数是合规的改动的只有明显该拆的那批。skipComments: true很实用函数里的详细注释不该被算进长度否则会逼着人删注释来凑行数。# pyproject.toml —— 一份配置同时承接格式、导入顺序和复杂度 [tool.ruff] line-length 120 target-version py311 [tool.ruff.lint] select [E, F, W, I, N, C901, B, UP] ignore [E501] # 行宽交给 formatter避免两边打架 mccabe { max-complexity 15 } [tool.ruff.lint.per-file-ignores] tests/** [S101] # 测试文件允许 assert migrations/** [E501, N806] # 自动生成的迁移脚本放宽select里的N是 pep8-naming 命名规则C901是圈复杂度I是导入排序B是 bugbear 的常见陷阱。ignore [E501]这条看起来多余实则关键——如果 formatter 和 linter 都管行宽长字符串的换行位置会来回改每次提交都产生无意义 diff。自动生成的迁移脚本这类目录直接整片豁免比事后逐条加 noqa 干净得多。2.4 映射表本身要跟着仓库走把上面三类配置整理成一份docs/coding-standards/rule-map.md每条规则三列规范条款编号、对应工具规则名、豁免条件。新同事改配置时先查这张表就不会出现两个人同时给同一个条款加规则的情况。规范里没写但工具报错的情况要么补进 PDF要么关掉规则不要留着工具比规范严这种悬空状态——时间久了没人说得清哪个才是准绳。3. 命名、注释与异常处理编码规范里最容易被跳过的高价值条款3.1 命名规范的可检查部分与不可检查部分规范里最常见的写法是命名要有意义、要见名知意这句话本身无法执行但拆开之后有一部分是可以落地的。可执行的是这几条类名大驼峰、函数和变量小写下划线、布尔值以 is/has/can/should 开头、常量全大写、禁止拼音首字母缩写、禁止单字母命名循环变量 i/j/k 例外。# 命名条款的可执行化只约束能自动判定的部分 [tool.ruff.lint.pep8-naming] class-naming-style PascalCase function-naming-style snake_case variable-naming-style snake_case # 框架回调、测试钩子等既有约定白名单放过 ignore-names [setUp, tearDown, test_*, visit_*]剩下那部分——比如data、info、temp这类空泛命名——交给评审清单。我一般会在评审模板里加一条固定提问这个变量名隔两周你自己还认得出它装的是什么吗把不可执行的部分变成具体的提问比写成条款有用得多。3.2 注释规范的底线不是覆盖率是完整性和时效性注释覆盖率不低于 30%是我见过最容易被反噬的条款它会催生大量# 自增计数器这种噪音。真正该卡的是三件事公共 API 的 docstring 参数齐全、注释掉的死代码一律删除、TODO 必须带责任人和期限。# 只检查公共接口的 docstring 完整性不统计比例 [tool.ruff.lint] select [D] [tool.ruff.lint.pydocstyle] convention google#!/usr/bin/env bash # 禁止裸 TODO必须写成 TODO(姓名, 2025-12-31): 说明 # -P 启用 PCRE 才能用否定预查-n 打印行号 if grep -rnP TODO(?!\([A-Za-z], \d{4}-\d{2}-\d{2}\)) \ --include*.py --include*.ts --include*.java src/; then echo 存在未标注责任人和期限的 TODO请补全后再提交 exit 1 fi(?!...)是负向前瞻匹配所有后面不是括号责任人的 TODO只有格式完全正确的才放行。这条规则上线后最直接的效果不是 TODO 变少而是每条 TODO 都有人认领季度清理时能直接按名字找人。3.3 异常与返回码统一出口比禁止吞异常更重要规范写禁止吞异常是对的但更根本的是有没有一个统一的异常出口。如果每层代码都能随手决定返回什么错误结构那规范再多也拦不住。class AppError(Exception): 所有可预期业务异常的基类code 是对外契约的一部分。 code: str INTERNAL_ERROR http_status: int 500 def __init__(self, message: str, *, detail: dict | None None): super().__init__(message) self.message message self.detail detail or {} class ParamInvalid(AppError): code PARAM_INVALID http_status 400 class ResourceNotFound(AppError): code RESOURCE_NOT_FOUND http_status 404业务层只允许抛AppError的子类HTTP 状态码和响应体结构全部由边界层统一翻译。这样一来code字段就成了对外契约新增错误码要走评审而不是随手raise Exception(参数错了)。配套再开两条 linter 规则Ruff 的E722禁止裸 exceptESLint 的no-empty禁止空的 catch 块——这两条能拦住绝大多数吞异常的写法。3.4 日志规范级别划分和敏感字段脱敏日志规范最容易写成重要操作要打日志这种条款没有任何约束力。可执行的版本是两张表加一段代码。级别划分DEBUG 只在本地开INFO 记录状态变更和关键入参WARN 记录可恢复的异常和降级ERROR 记录需要人介入的失败并进告警通道。级别使用场景是否进告警线上是否默认开启DEBUG本地排查、循环内细节否否INFO请求入口出口、状态流转否是WARN重试成功、降级兜底否是ERROR业务失败、依赖不可用是是import json import logging # 规范第 7.4 节日志中禁止出现完整手机号、身份证、令牌 SENSITIVE_KEYS {password, id_card, phone, token, secret} class JsonFormatter(logging.Formatter): def format(self, record: logging.LogRecord) - str: payload { level: record.levelname, logger: record.name, msg: record.getMessage(), trace_id: getattr(record, trace_id, -), } # 兜底脱敏即便业务代码误传也不会把敏感字段原样落盘 for key in list(payload): if key in SENSITIVE_KEYS: payload[key] *** return json.dumps(payload, ensure_asciiFalse)结构化日志的好处是脱敏可以做成兜底逻辑而不是指望每个调用点都记得处理。trace_id用getattr取并给默认值是为了让没有链路上下文的日志也能正常输出不至于因为缺字段直接抛异常把主流程带崩。4. 提交前拦截与 CI 卡点让编码规范在流水线里自动执行4.1 pre-commit 的执行顺序有讲究单向钩子的配置最怕顺序错乱先 lint 再 format会得到lint 报错、format 改了、报错消失的假象下一轮又冒出来。正确顺序永远是先格式化再检查。# .pre-commit-config.yaml repos: - repo: https://github.com/pre-commit/pre-commit-hooks rev: v4.6.0 # 版本必须固定别用 main hooks: - id: trailing-whitespace - id: end-of-file-fixer - id: check-merge-conflict - id: check-added-large-files args: [--maxkb512] - repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.5.0 hooks: - id: ruff-format # 先格式化 - id: ruff # 再 lint args: [--fix, --exit-non-zero-on-fix] - repo: local hooks: - id: check-todo-owner name: TODO 必须带责任人和期限 entry: bash scripts/check_todo.sh language: system files: \.(py|ts|java)$rev用固定 tag 而不是分支是踩过坑之后的习惯——上游某次改了默认行为第二天全组的提交都会挂排查半天才发现是钩子版本漂了。--exit-non-zero-on-fix让自动修复也算失败一次强制开发者重新git add避免修了但没提交进这次 commit否则 CI 上会再报一遍同样的错。4.2 CI 三级门禁什么该断什么该提示把所有检查都设成阻断团队会直接绕过全设成提示等于没有。我的分法是三级安全类和格式类阻断质量趋势类提示专家规则只出报告。级别判据典型规则CI 行为阻断可能导致线上事故或契约破坏高危安全问题、格式检查、编译失败不允许合并警告影响可维护性但不立即出事复杂度超阈值、重复代码块、无效代码允许合并记入趋势提示需要人判断死代码、注释完整性、命名可疑只出报告# .gitlab-ci.yml 片段 stages: [lint, test, build] coding-standards:blocking: stage: lint script: - ruff format --check src/ # 格式必须已统一 - ruff check src/ # 静态检查选中的规则全开 - bandit -r src/ -ll # 只断中高危安全问题 allow_failure: false coding-standards:advisory: stage: lint script: - radon cc src/ -a -nb complexity.txt # 复杂度趋势供看板采集 - vulture src/ --min-confidence 80 # 死代码只提示 artifacts: paths: [complexity.txt] expire_in: 30 days allow_failure: truebandit -ll只报告 medium 及以上低危项在存量代码里数量太大全开会淹没真正的问题。allow_failure: true加上 artifacts 保留等于把质量数据变成可以画趋势线的输入而不是一次性的红叉。4.3 存量代码的增量收口策略在一个跑了三年、几十万行的仓库上一次性开启全部规则结果通常是几千条错误然后有人提一个 MR 把规则关掉。正确做法是基线冻结加增量检查只对本 MR 改动的文件跑严格规则存量文件按旧规则。# 只对变更文件跑严格检查存量债务不阻塞新提交 CHANGED$(git diff --name-only --diff-filterACMR origin/main...HEAD \ | grep -E \.(py|ts|java)$ || true) if [ -n $CHANGED ]; then echo $CHANGED | xargs ruff check --no-cache fi--diff-filterACMR只取新增、复制、修改、重命名的文件删掉的文件没必要再检查。这套策略的关键在于让新代码必须合规成为硬约束存量代码允许慢慢改配合每季度一次专项清理一年左右能把基线拉上来。复杂度这类需要看上下文的值我还习惯加一个增量阈值——对比 MR 前后的函数复杂度只卡本次改动让复杂度变差了的情况比卡绝对值更容易被接受。5. 规范版本化与豁免度量编码规范 PDF 的长期维护技巧5.1 把 PDF 换成带版本和规则 ID 的规范仓库PDF 最大的问题是没法评审、没法追溯、没法知道哪条还生效。我会在仓库里建docs/coding-standards/目录按主题拆成多个 markdown 文件每条规则带一个稳定 ID格式是CS-主题-序号比如CS-NAMING-003。docs/coding-standards/ ├── README.md # 规范总览与变更记录 ├── 01-format.md # 格式类对应 EditorConfig 与 Prettier ├── 02-naming.md # 命名类 ├── 03-exception.md # 异常与错误码 ├── 04-logging.md # 日志 ├── 05-security.md # 安全类采标来源单独标注 └── rule-map.md # 规则 ID - 工具规则名的映射每个规则文件里每条规则写成固定的三行规则 ID 与一句话描述、对应的工具规则名、豁免条件。rule-map.md反过来索引配置改动时先查这里。规范变更走正常的 MR 流程有 diff、有评审、有提交记录谁在什么时候为什么放宽了某条规则翻 git log 就能看到比 PDF 上的版本 1.2靠谱得多。5.2 三个能验证规范是否真的生效的指标规范发布不等于执行执行也不等于生效。我一般盯这三个数每季度看一次趋势。指标采集方式健康区间异常信号豁免密度统计 eslint-disable、noqa、SuppressWarnings 数量每千行少于 5 处持续上升说明规则脱离实际评审风格类评论占比评审记录按标签分类低于 10%偏高说明格式条款没自动化同类缺陷重复率缺陷库按根因归类逐季下降不降说明规范没针对真实问题豁免密度是最灵敏的指标。规则太严或者和实际写法冲突时开发者不会去提 MR 改规范而是就地加一行# noqa这个数字会悄悄涨上去。# 定期扫一遍豁免注释分布定位规则设计问题 grep -rn eslint-disable\|# noqa\|SuppressWarnings \ --include*.py --include*.ts --include*.java src/ \ | awk -F: {print $1} | sort | uniq -c | sort -rn | head -20按文件聚合输出前 20 名如果豁免集中在某几个目录说明那块的规范和实际场景不匹配多半是生成代码、适配层或测试夹具这类特殊场景应该整片开per-file-ignores而不是让每个人逐行加注释。豁免注释必须带规则 ID 和简短理由比如# noqa: C901 状态机展开更易读季度清理时按理由决定是删掉还是写进规范的例外条款。规则 ID 缺失的豁免注释直接加一条自定义检查卡住。本文还有配套的精品资源点击获取
