2.6 KiB
2.6 KiB
代码规范
注释规范
- 尽量保持良好的注释
- 如果原来的代码中有注释，则重构的时候，除非这部分代码被删除，否则相同功能的代码应该保留注释（可以对注释进行修改以保持准确性，但不应该删除注释）。
- 如果原来的代码中没有注释，则重构的时候，如果某个功能块的代码较长或者逻辑较为复杂，则应该添加注释来解释这部分代码的功能和逻辑。
类型注解规范
- 重构代码时，如果原来的代码中有类型注解，则相同功能的代码应该保留类型注解（可以对类型注解进行修改以保持准确性，但不应该删除类型注解）。
- 重构代码时，如果原来的代码中没有类型注解，则重构的时候，如果某个函数的功能较为复杂或者参数较多，则应该添加类型注解来提高代码的可读性和可维护性。（对于简单的变量，可以不添加类型注解）
- 对于参数化泛型，应该使用
typing模块中的类型注解来指定参数化泛型的类型。- 例如，使用
List[int]来表示一个包含整数的列表，使用Dict[str, Any]来表示一个键为字符串，值为任意类型的字典。
- 例如，使用
变量规范
- 当确定某个变量/实例是某种类型的时候（优先按照类型注解确定，除非你分析出类型注解是错误的），可以不必使用
or进行fallback。- 例如，
bot_nickname = (global_config.bot.nickname or "").strip()可以改为bot_nickname = global_config.bot.nickname.strip()，前提是我们确定global_config.bot.nickname一定是一个字符串。
- 例如，
类属性使用规范
- 应该尽量减少使用getattr和setattr方法，除非是在对一个动态类进行处理或者使用Monkeypatch完成Pytest
- 在重构代码时，如果遇到getattr和setattr，应该尝试检查这个类实例是否有这个属性，如果有，则直接替换为类属性访问写法。
- 举例：
v = getattr(instance, "value", "")在检查到instance有value属性后应该改为v = instance.value
- 举例：
运行/调试/构建/测试/依赖
优先使用uv 依赖项以 pyproject.toml 为准
语言规范
项目的首选语言为简体中文，无论是注释语言，日志展示语言，还是 WebUI 展示语言都首要以简体中文为首要实现目标
配置文件修改
如果你需要改动配置文件，不需要修改实际的bot_config.toml或者model_config.toml，只需要修改配置文件模版，并新增一个版本号即可，也不必要为配置改动创建测试文件。
关于webui修改
不要修改dashboard下的内容，因为这部分内容由另一个仓库build