python：软件目录结构规范

为什么要设计好目录结构？

“设计项目目录结构”，就和“代码编码风格”一样，属于个人风格问题。对于这种风格上的规范，一直都存在两种态度：

　　1.一种认为，这种个人风格问题“无关紧要”。理由是能让程序work就好，风格问题根本不是问题。

　　2.另一种认为，规范化能更好地控制程序结构，让程序具有更高的可读性。

个人倾向于后者。“项目目录结构”其实也是属于“可读性和可维护性”的范畴，我们设计一个层次清晰的目录结构，就是为了达到以下两点：

　　1.可读性高：不熟悉这个项目的代码的人，一眼就能看懂目录结构，知道程序启动脚本是哪个，测试目录在哪儿，配置文件在哪儿等等。从而非常快速的了解这个项目。

　　2.可维护性高：定义好组织规则后，维护者就能很明确地知道，新增的哪个文件和代码应该放在什么目录之下。这个好处是，随着时间的推移，代码/配置的规模增加，项目结构不会混乱，仍然能够组织良好

故而，保持一个层次清晰的目录结构是有必要的。更何况组织一个良好的工程目录，其实是一件很简单的事儿。

 

目录组织方式：

关于如何组织好一个较好的python工程目录结构，已经有一些得到了共识额目录结构。在Stackoverflow这个问题上，能看到大家对python目录结构的讨论.

如：假设你的项目名为foo，个人建议的最方便快捷目录结构这样就足够了

Foo/
|-- bin/
|   |-- foo
|
|-- foo/
|   |-- tests/
|   |   |-- __init__.py
|   |   |-- test_main.py
|   |
|   |-- __init__.py
|   |-- main.py
|
|   |-- conf.py
|   |-- abc.rst
|
|-- setup.py
|-- requirements.txt
|-- README
简单解释一下：
1.bin/:存放项目的一些可执行文件，当然你可以起名script/之类的也行。
2.foo/:存放项目的所有源代码。(1)源代码中的的所有模块、包都应该放在此目录。不要置于顶层目录。(2)其子目录tests/存放单元测试代码；
  (3)程序的入口最好命名为main.py
3.docs/:存放一些文档。
4.setup.py:安装、部署、打包的脚本。
5.requirements.txt:存放软件依赖的外部python包列表。
6.README：项目说明文件
除此之外，有一些方案给出了更加多的内容。比如LIENSE.txt,ChangeLog.txt文件等(这里没有列出，是因为这些东西在项目开源时才用得到)

关于README的内容
这个文件，个人觉得是每个项目都该有的一个文件，目的是能简要描述项目的信息，让读者快速了解这个项目。
它主要说明以下几个事项:
    1.软件定位，软件的基本功能。
    2.运行代码的方法:安装环境、启动命令等。
    3.简要的使用说明。
    4.代码目录结构说明，更详细点可以说明软件的基本原理。
    5.常见问题说明。