对于一个代码项目,好的目录结构是必不可少的。
我们为什么需要设计好的目录结构?
好的目录结构,意味着好的 可读性 和 可维护性,
- 可读性好:刚接触项目的人,一眼就能看懂目录结构,知道哪里是 源码,哪里是 配置文件,哪里是 文档,从而能够非常快速的了解这个项目
- 可维护性好:维护者能够很明确地知道,新增的文件跟代码应该放到什么目录,随着时间的推移,代码/配置的规模增加,项目结构不会混乱,仍然能够组织良好。
我们应该如何对项目目录合理地进行组织?
组织一个良好的项目目录其实不难。你并不需要从零开始造轮子,已经有人总结出了一些不错的目录结构并得到了大家的广泛共识,你只要能够理解其思想,会使用就够了。
项目目录结构的简单模板
假设你的项目名为foo,推荐的、比较方便的目录结构可以是这样,
Foo/
|-- bin/
| |-- foo
|
|-- foo/
| |-- tests/
| | |-- __init__.py
| | |-- test_main.py
| |
| |-- __init__.py
| |-- main.py
|
|-- docs/
| |-- conf.py
| |-- abc.rst
|
|-- setup.py
|-- requirements.txt
|-- README
其中,
- bin/: 存放项目的一些可执行文件,当然你可以起名script/之类的也行。
- foo/: 存放项目的所有源代码。(1) 源代码中的所有模块、包都应该放在此目录。不要置于顶层目录。(2) 其子目录tests/存放单元测试代码; (3) 程序的入口最好命名为main.py。
- docs/: 存放一些文档。
- setup.py: 安装、部署、打包的脚本。
- requirements.txt: 存放软件依赖的外部Python包列表。
- README: 项目说明文件。
除此之外,有一些方案给出了更加多的内容。比如LICENSE.txt,ChangeLog.txt文件等,这里没有列出,因为这些东西主要是项目开源的时候需要用到。
项目说明 README
README每个项目都应该有的一个文件,作用是能够 简要描述该项目的信息,让读者快速了解这个项目。
它最好能够说明以下几个事项:
- 软件定位,软件的基本功能。
- 运行代码的方法: 安装环境、启动命令等。
- 简要的使用说明。
- 代码目录结构说明,更详细点可以说明软件的基本原理。
- 常见问题说明。
可以参考Redis源码中Readme的写法,这里面简洁但是清晰的描述了Redis功能和源码结构。
https://github.com/antirez/redis#what-is-redis
依赖包 requirements.txt 和 setup.py
配置文件 config
很多项目对配置文件的使用做法是:
- 配置文件写在一个或多个python文件中,比如此处的conf.py。
- 项目中哪个模块用到这个配置文件就直接通过import conf这种形式来在代码中使用配置。
实例解读
以流行的YOLOv3XmlGenerator
的项目为例,大致的文件目录如下图所示
其中
- README.md 项目介绍,一般包括使用的环境,安装的方法,软件的基本原理、测试数据及常见问题等,越详细越好
- requirements.txt 记录依赖的软件包及对应的版本号,方便读者明确项目使用了哪些Python包,可以使用命令安装所有的依赖包
pip install -r requirements.txt
,另外,可以使用pipreqs
这个工具来生成requirements.txt - setup.py, 安装、部署、打包的脚本。
- docs 文档目录,项目配置文件通常也放在这里,关于项目配置文件,可以看看这篇文章,讲的比较全 https://martin-thoma.com/configuration-files-in-python/
- extras 有时候会使用到一些C/C++库,一般放在这个文件夹里
- scripts 存放脚本文件,比如代码仓库不适合存放很大的二进制文件,这时候可以写个脚本去拉取
- yolov3xmlgenerator 项目源码文件夹,入口文件建议命名为
main.py
,再配上__init__.py文件,另外,单元测试的代码也放在这块
下面的东西主要是项目开源的时候需要用到
- LICENSE 协议文件,可以参考这篇文章 https://www.jianshu.com/p/a57c13631d5e,讲的很详细
- ChangeLog.txt 记录版本发布的release note
- .gitignore 如果使用的是git代码管理工具,表明上传时忽略的文件,如果您使用的是svn,请忽略
参考:
[3] 结构化您的工程