算法实现标准

核心实现要求

所有算法实现都必须遵循严格的标准，以保持教育质量和代码一致性。每个算法提交都必须实现核心功能要求，使其适合教育用途和集成到更大的程序中。

算法定义和结构

本存储库中的算法定义为一个或多个函数或类，它们接受输入、执行计算或数据操作、返回输出，并具有最少量的副作用。实现必须打包好，以便于集成到更大的程序中。

算法实现结构 来源：CONTRIBUTING.md43-62

命名约定和代码风格

所有实现都必须遵循 Python 命名约定，以确保可读性和一致性。存储库强制执行特定的命名模式，以帮助读者理解算法的目的并方便代码维护。

组件	约定	示例
函数	snake_case	`greatest_common_divisor()`
变量	snake_case	`input_array`, `result_value`
常量	UPPER_CASE	`MAX_ITERATIONS`
类	CamelCase	`BinarySearchTree`
文件	snake_case.py	`quick_sort.py`
目录	snake_case	`dynamic_programming/`

关键命名要求包括：

使用描述性名称，避免冗余注释。
避免使用单字母变量名，除非是短暂的循环计数器。
展开缩写以提高清晰度（greatest_common_divisor() 而不是 gcd()）。
注重函数和类名称，使其向读者清晰地传达目的。

来源：CONTRIBUTING.md80-84

类型提示和函数签名

所有函数参数和返回值都必须包含 Python 类型提示。此要求允许使用 mypy 进行静态类型检查，并为教育目的改进代码文档。

存储库的 CI 管道运行 mypy --ignore-missing-imports 来验证所有类型提示，确保所有实现的一致性。

来源：CONTRIBUTING.md162-169

文档标准

Docstring 要求

每个函数都必须包含全面的 docstring，以用于文档和教育目的。Docstring 应包含算法目的的清晰说明、可选的详细说明以及适用的来源材料参考。

Docstring 组件和结构 来源：CONTRIBUTING.md116-125 project_euler/README.md30-48

模块级文档

算法文件应包含模块级 docstring，提供上下文和参考。对于 Project Euler 解决方案，模块 docstring 必须包含完整的题目说明和解决方案方法。

示例模块结构

题目说明（针对 Project Euler）
算法说明或方法
对原始材料的引用
导入语句（在 docstring 之后）

来源：project_euler/README.md22-24

测试要求

Doctest 实现

所有函数都必须包含 doctests，以演示有效用法和错误处理。Doctests 作为可执行的文档，并由 CI 管道自动验证。

Doctest 要求

测试有效输入场景及其预期输出。
测试边缘情况和边界条件。
测试错误情况及其适当的异常处理。
在适用时使用多种输入类型。
避免测试 Project Euler 问题的最终答案。

Doctests 在本地使用 python3 -m doctest -v 执行，在 CI 管道中使用 pytest 执行。

来源：CONTRIBUTING.md126-146

错误处理标准

算法必须使用 Python 异常来处理无效输入，以实现适当的错误处理。这确保了健壮的行为和清晰的错误消息，以便用于教育。

常见的异常模式

ValueError 用于无效的参数值
TypeError 用于不正确的参数类型
用于特定于算法的错误的自定义异常

来源：CONTRIBUTING.md56

代码质量标准

自动化代码格式化

所有提交都必须通过 CI 管道强制执行的自动化代码质量检查。存储库使用多种工具来确保代码风格和质量的一致性。

代码质量管道 来源：CONTRIBUTING.md64-100

工具要求

工具	目的	命令	要求
Black	代码格式化	`black .`	推荐要求
Ruff	Linting and style	`ruff check`	必填
MyPy	类型检查	`mypy --ignore-missing-imports .`	必填
Pre-commit	Automated hooks	`pre-commit install`	推荐要求

所有提交都必须在接受前通过 ruff . 测试。存储库配置可确保所有算法实现的代码风格一致。

来源：CONTRIBUTING.md88-100

文件组织标准

文件和目录命名

严格的命名约定可确保一致的存储库结构，并支持 CI 系统进行自动化处理。

文件名规则

所有文件名使用 snake_case。
算法文件的扩展名必须为 .py。
尽可能避免创建新目录。
遵循现有的目录标准。

目录结构

将实现纳入现有的目录结构。
仅为新算法类别创建目录。
使用遵循 snake_case 的描述性目录名称。

来源：CONTRIBUTING.md179-181

Project Euler 特定要求

Project Euler 解决方案有额外的组织要求，以支持自动验证和答案检查。

Project Euler 目录结构 来源：project_euler/README.md16-21

Project Euler 命名约定

目录：problem_XXX（3 位零填充数字）
文件：sol1.py、sol2.py（用于多个解决方案）
每个问题目录都需要空的 __init__.py 文件。

解决方案函数要求

函数命名为 solution，默认参数匹配问题输入。
在不带参数调用时，返回问题答案。
Doctests 不应测试最终答案（单独验证）。

来源：project_euler/README.md26-31

导入和依赖指南

算法实现应最大限度地减少外部依赖，以保持教育清晰度和降低复杂性。

导入指南

对于基本算法，避免使用外部库。
仅对需要专门功能的高度复杂算法使用外部库。
提交时将新依赖项添加到 requirements.txt。
将所有导入放在模块级 docstring 之后。

首选 Python 构造

列表推导式优于 map、filter、reduce。
用于内存效率的生成器表达式。
在适当的情况下使用内置函数和标准库。

来源：CONTRIBUTING.md171-174