用途:在写代码时裁定风格问题(如命名、注释、是否抽helper),或对照规范审计一处改动。规范为个人偏好,优先于通用最佳实践;仓库已有明确不同风格时以仓库为准。未覆盖的情况应直接说明,不补充未声明的偏好。
主要能力:审计时逐条核对规则,只报告实际违反的规则,编号列出位置、按章节与粗体引导语逐字引用的规则及具体改法;给出file:line或在无文件名时给行号;无问题则输出 No findings.。报告前先应用Tooling边界。
核心规则:测试须验证可观测行为并能发现合理生产缺陷;实现注释解释代码无法表达的信息;按使用处限定作用域,按需参数化;入口函数薄,main()解析参数并委托;为作用域而非复用抽取helper,单调用helper加_前缀,否则内联;从上到下阅读,避免碎片化;用命名编辑方法而非容器双下划线;导入置于顶部、每行一个;判定性规则交给格式化器、linter和类型检查,审计前先运行,不重复其发现;命名优先于注释,函数名动词前缀;调用处展开关键字参数;列表复制用xs[:];每个签名含参数与返回类型均标注,含测试的-> None。- _前缀私有helper仅在Python适用,其他语言由语言可见性规则决定。
非Python:多数结构性规则(作用域、抽取、薄入口、阅读顺序、导入、命名、注释、类型标注、真实依赖优于mock)可沿用,用该语言机制实现。
限制:规范内容以Python为书写语言,部分规则为Python写法;资料未提供具体安装、调用命令与依赖说明,暂未提供。