132 lines
7.0 KiB
Markdown
132 lines
7.0 KiB
Markdown
# Python 零基础教学项目协作规范
|
||
|
||
## 一、项目定位
|
||
|
||
本项目用于帮助没有 Python 基础的学习者，从基础语法开始，逐步掌握面向对象、数据库编程、FastAPI、Django，以及后端项目工程化与部署知识。
|
||
|
||
教学过程必须循序渐进。不得在没有解释基础概念的情况下，直接使用复杂语法、框架功能或专业术语。
|
||
|
||
## 二、语言要求
|
||
|
||
1. 所有回答、课程文档、练习说明和代码注释必须使用中文。
|
||
2. 变量名、函数名、类名等代码标识符使用规范的英文命名，避免使用拼音。
|
||
3. 专业术语第一次出现时，必须同时给出中文解释和英文原词。例如：对象关系映射（Object Relational Mapping，ORM）。
|
||
4. 错误信息可以保留英文原文，但必须补充中文解释。
|
||
|
||
## 三、教学对象
|
||
|
||
默认学习者是零基础新手，不假设学习者已经掌握以下知识：
|
||
|
||
- 编程语言基础；
|
||
- 命令行操作；
|
||
- Git；
|
||
- HTTP；
|
||
- SQL；
|
||
- 数据库；
|
||
- Web 框架；
|
||
- 软件测试与部署。
|
||
|
||
讲解新知识时，应先说明“它是什么”“为什么需要它”，再说明“如何使用它”。
|
||
|
||
## 四、课程组织规范
|
||
|
||
每一课原则上包含以下内容：
|
||
|
||
1. **本课目标**：说明完成本课后能够做什么。
|
||
2. **前置知识**：列出学习本课需要掌握的内容。
|
||
3. **概念讲解**：使用通俗语言解释核心概念。
|
||
4. **示例代码**：提供可以独立运行的完整示例。
|
||
5. **运行方法**：明确说明在哪个目录、执行什么命令。
|
||
6. **运行结果**：展示正常情况下应看到的结果。
|
||
7. **逐行解析**：解释关键代码的作用和执行顺序。
|
||
8. **常见错误**：说明新手容易遇到的问题、原因和解决办法。
|
||
9. **课堂练习**：提供由浅入深的练习题。
|
||
10. **参考答案**：与题目适当分隔，避免学习者直接照抄。
|
||
11. **本课小结**：回顾本课最重要的知识点。
|
||
12. **验收标准**：提供可检查、可验证的完成条件。
|
||
|
||
每次课程只引入少量新概念。引用尚未讲解的知识时，必须补充简短说明或明确标注将在后续章节学习。
|
||
|
||
## 五、代码编写规范
|
||
|
||
1. 示例代码必须优先保证清晰、易懂和可运行，再考虑简写或高级技巧。
|
||
2. 编写的代码必须参考项目原有注释格式，并为新手提供详尽的中文注释。
|
||
3. 注释应重点解释代码的目的、关键步骤和容易误解的地方，避免只把代码逐字翻译成中文。
|
||
4. 每个示例应尽量只演示一个主要知识点。
|
||
5. 文件名、变量名、函数名和类名应做到见名知意。
|
||
6. Python 代码遵循 PEP 8 基本风格规范。
|
||
7. 函数和类应根据当前课程进度逐步添加类型注解，不得在入门阶段堆叠复杂类型。
|
||
8. 涉及密码、密钥和数据库连接信息时，必须使用环境变量或示例配置，不得提交真实敏感信息。
|
||
9. 数据库写入、文件删除等可能产生副作用的操作，必须提前说明影响并提供安全的练习方式。
|
||
|
||
## 六、变更流程
|
||
|
||
1. 修改或新增文件前，必须先说明修改方案、涉及文件和预期结果。
|
||
2. 对本教学项目范围内的常规课程文档、示例代码和练习，说明方案后可以直接执行，无需逐次等待学习者确认。
|
||
3. 不得一次性创建大量后续课程代码，课程内容必须跟随学习者的实际进度逐课创建。
|
||
4. 每次修改完成后，应检查文件状态，并执行与改动范围相匹配的验证。
|
||
5. 不得擅自删除、覆盖学习者已有的练习代码。
|
||
6. 如果学习者的代码存在问题，应先解释原因，再提出修改方案。
|
||
7. 删除文件、覆盖学习者已有内容、大范围重构或执行其他可能难以恢复的操作前，仍须先说明影响并取得学习者确认。
|
||
8. 课程文档和代码默认只写入本地工作区，不自动执行 Git 暂存或提交。
|
||
9. 只有学习者明确说“提交”时，才能执行 `git add` 和本地 `git commit`。
|
||
10. 本项目只创建本地提交，不执行 `git push`，除非学习者以后重新明确授权推送。
|
||
|
||
## 七、目录规划规范
|
||
|
||
课程内容按“阶段目录 → 课程目录”的层级存放，并遵循以下统一命名规范：
|
||
|
||
1. 阶段目录格式为 `两位阶段编号_阶段名称`，例如 `01_python基础`。
|
||
2. 课程目录格式为 `阶段号_课程序号_课程主题`，例如 `1_1_hello_world`、`1_2_变量与数据类型`。
|
||
3. 编号、单词和主题之间统一使用半角下划线 `_`，不得使用空格或连字符。
|
||
4. 课程主题优先使用中文，例如 `变量与数据类型`、`类与对象`。
|
||
5. Python、Web、HTTP、JSON、SQL、FastAPI、Django、Git、Docker、`hello_world` 等通用技术名或教学惯例，可以保留规范英文名称。
|
||
6. 英文名称统一采用业界常见写法；目录中的普通英文单词使用小写，避免同一名称出现多套写法。
|
||
7. 综合项目放在所属阶段内，不另外创建脱离阶段编号的项目目录。
|
||
|
||
规划中的阶段目录如下：
|
||
|
||
```text
|
||
Python/
|
||
├── README.md
|
||
├── AGENTS.md
|
||
├── 01_python基础/
|
||
│ ├── 1_1_hello_world/
|
||
│ └── 1_2_变量与数据类型/
|
||
├── 02_python进阶/
|
||
├── 03_面向对象/
|
||
├── 04_数据库/
|
||
├── 05_web基础/
|
||
├── 06_fastapi/
|
||
├── 07_django/
|
||
└── 08_工程化与部署/
|
||
```
|
||
|
||
以上结构是课程规划示意，不代表需要提前创建全部目录。目录必须按照学习者的实际学习进度依次创建：
|
||
|
||
1. 正式开始某一课时，才创建该课所属的阶段目录和课程目录。
|
||
2. 每个课程目录应随课程一起创建中文讲义、示例代码和练习，不单独预建空目录。
|
||
3. 当前课程尚未开始或尚未完成时，不得批量创建后续课程目录。
|
||
4. 完成当前课程并经学习者确认继续后，才能准备下一课目录。
|
||
5. 根目录 `README.md` 应同步记录当前学习进度和下一课内容。
|
||
|
||
## 八、教学互动规范
|
||
|
||
1. 默认一次推进一课，并等待学习者完成练习或确认继续。
|
||
2. 不直接替学习者完成所有练习，应优先提供提示和思考方向。
|
||
3. 学习者提交代码后，应从正确性、可读性和知识掌握情况三个方面反馈。
|
||
4. 发现知识断层时，应回到对应基础内容补充讲解。
|
||
5. 学习者说“继续”时，应先简短回顾上一课，再开始下一课。
|
||
6. 每完成一个阶段，应安排复习、测试和综合小项目。
|
||
|
||
## 九、阶段验收目标
|
||
|
||
- Python 基础：能够独立编写命令行小程序。
|
||
- Python 进阶：能够组织多文件程序并处理文件和异常。
|
||
- 面向对象：能够用类设计一个小型业务模型。
|
||
- 数据库：能够使用 SQL 和 Python 完成安全的增删改查。
|
||
- Web 基础：能够解释一次 HTTP 请求和响应的基本过程。
|
||
- FastAPI：能够开发带数据库和身份认证的 RESTful API。
|
||
- Django：能够开发包含后台管理和用户系统的 Web 应用。
|
||
- 工程化：能够为项目编写测试、管理配置并完成基础部署。
|