【Pythonic】01-Python项目及代码规范

---

参考内容：

• 【python中如何组织项目代码】
• 【中英双字】编写更好的 Python 函数的 5 个技巧
• 【Python 代码这样写，想不让别人叫你大佬都难】
• 深度学习项目，代码结构、风格和习惯，让自己的代码更Pythonic! - 知乎 (zhihu.com)
• python项目结构 - 知乎 (zhihu.com)

---

Python 项目规范

project_name/
│
├── data/                   # 数据存储目录
│   ├── raw/                # 原始未处理的数据
│   ├── processed/          # 处理过的数据
│   └── external/           # 外部数据集
│
├── notebooks/              # Jupyter notebooks文件目录
│   └── *.ipynb             # 各种notebook文件
│
├── src/                    # 源代码目录
│   ├── __init__.py         # 使src成为一个包
│   ├── data/               # 数据处理代码
│   │   ├── __init__.py
│   │   └── data_loader.py  # 数据加载和预处理
│   │
│   ├── models/             # 模型定义和训练代码
│   │   ├── __init__.py
│   │   ├── model.py        # 模型架构定义
│   │   └── train.py        # 模型训练脚本
│   │
│   ├── utils/              # 工具函数和辅助代码
│   │   ├── __init__.py
│   │   └── helper.py       # 一些工具函数
│   │
│   ├── config/             # 配置文件目录
│   │   ├── __init__.py
│   │   └── config.json     # 超参数和配置文件
│   │
│   └── inference/          # 推理代码
│       ├── __init__.py
│       └── inference.py    # 模型推理和预测
│
├── tests/                  # 单元测试目录
│   ├── __init__.py
│   ├── test_data_loader.py # 数据加载的测试
│   ├── test_model.py       # 模型相关测试
│   └── test_utils.py       # 工具函数测试
│
├── scripts/                # 脚本文件目录
│   ├── preprocess.py       # 数据预处理脚本
│   ├── train.py            # 训练模型的脚本
│   └── evaluate.py         # 模型评估脚本
│
├── logs/                   # 日志文件目录
│   └── train.log           # 训练日志
│
├── models/                 # 训练好的模型存放目录
│   └── model.pth           # 训练好的模型文件
│
├── requirements.txt        # Python依赖包文件
├── README.md               # 项目说明文件
├── setup.py                # 安装脚本
└── .gitignore              # Git忽略文件

• data/: 存放项目使用的所有数据，分为原始数据（raw）和处理后的数据（processed）。
• notebooks/: 存放Jupyter notebooks，方便进行数据分析和模型原型设计。
• src/: 存放所有源代码，包括数据处理、模型定义、训练、推理和配置文件等。
• tests/: 单元测试文件，确保各个模块功能的正确性。
• scripts/: 存放用于数据预处理、模型训练、模型评估等独立运行的脚本。
• logs/: 保存训练或运行过程中生成的日志文件，便于调试和分析。
• models/: 保存训练好的模型文件，便于后续加载和推理。
• requirements.txt: 环境配置文件，用于管理项目依赖。
• README.md: 项目说明文件，介绍项目的目的、使用方法等。
• setup.py: 用于安装项目依赖的脚本，方便项目的发布和安装。
• .gitignore: 指定哪些文件或目录不应该包含在Git版本控制中。

这个只是基本的目录结构，还可以不断添加其他目录，比如文档目录docs/，测试目录evaluation/

主要的代码存放在src/目录中，其中主要包括：

• data/ 数据处理模块
• models/ 模型代码模块
• config/ 模型配置文件以及相关模块，可以使用yaml或者json文件，方便实验
• utils/ 一些工具模块代码
• …

对于不同模块的代码，都需要通过__init__.py来使得这个模块可以被识别成一个独立的module；

其他目录基本是辅助作用，比如logs/，tests/，models/，scripts/

---

Python 代码规范

命名规范

• 类命名
  • 驼峰式
  • 首字母大写，不使用下划线
• 函数命名
  • 小写字母+下划线
  • 动词or动词短语
• 变量命名
  • 小写字母+下划线
• 常量命名
  • 大写字母+下划线
• 模块命名
  • 小写字母+下划线
  • 避免数字
  • 可以加上s变成复数形式

函数类型检查

在声明函数的时候声明参数类型以及返回值的类型，这样便于IDE进行上下文分析

函数注释

from typing import List

def find_max(numbers: List[int]) -> int:
    """Find the maximum number in a list.

    Args:
        numbers (List[int]): A list of integers.

    Returns:
        int: The maximum integer in the list.
    """
    return max(numbers)

主要包括：

• 第一行，简要的函数功能描述
• Args，参数类型：参数说明
• Returns，返回值类型：返回值说明

对于普通注释，注释尽量与代码对齐: