用途:在新增或修改 Python 代码时套用 flashdreams 的文档风格,使文档字符串、注释与文件头保持一致。
主要能力:规定每个 .py 文件以两行 SPDX 头(版权年份取当前年份,编辑已有文件时保留原年份)开头,随后空行、单行名词短语式模块 docstring、空行、导入;模块与类头部的清单应短而具体且易于核对,避免罗列全部参数或选项。函数与方法使用 Google 风格 docstring:首句祈使句、一行、以句号结尾,必要时含 Args:、Returns:、Raises:,不重复类型标注,仅在需要时可省略。类字段与模块级常量使用 PEP 257 属性 docstring(放在声明后一行),不写 Attributes: 段;_target 字段不写 docstring。内联注释只保留三类:说明原因或不变量、为多行长块做路标、为一句话中的疑难处加局部标记;不要复述下一行或断言消息。TODO 写作 # TODO: 简短描述,不写变更说明。文件内用 ## 双井号做分段标题。行宽随文件(常见约 88 字符),docstring 内代码引用用双反引号,交叉引用用 rST role,不使用 Markdown 语法;文档站沿用 Zensical,自定义段落需先注册。
适用场景:Python 项目写作、代码审查、让智能体产出的代码与既有人工代码风格难以区分。
限制:本规范不涉及运行时行为或性能;具体平台支持、收费与价格信息暂未提供;用户须自行确认所在项目是否采用同一风格。