Python入门之软件开发目录规范

时间:2022-12-15 10:46:46

本章重点:

    理解在开发人标准软件时,如何布局项目目录结构,以及注意开发规范的重要性。

    一、为什么要有好的目录结构

    二、目录组织的方式

    三、关于README的内容

    四、关于requirements.txt和setup.py

==================================================================================

 

一、为什么要有好的目录结构

 

  好的设计项目目录结构,就和编码风格一样,是每个程序员都有的风格,但是在流水化标准化作业过程中,个性和风格是不被鼓励的。

  如果你去维护一个非常不好读的项目,虽然实现逻辑并不复杂,但是对后续的维护者来说就是灾难。

 

  一个层次清晰的目录结构,可以提高程序的可维护性:

    1. 可读性高:

      后续维护人员可以一眼看懂目录结构,不必为复杂混乱的层次耗费大量精力。测试文件在哪,配置文件在哪会被放置在规范操作的地方,可以让后续人员快速的了解这个项目。

    2. 可维护性高:

      看清目录架构之后,维护者可以将后续新增的文件和代码按照规范放置在规定的地方,虽然后续代码和文件增多,但是项目目录并不会混乱,仍然能够快速组织良好

 

  所以说,保持一个层次清洗的目录结构是非常必要的,也是体现一个程序员思路和视野格局的一个标准

 

二、目录组织的方式

 

  目前各个开发语言在工程目录结构方面,已经取得了一些共识的目录结构.

  例如,如下的一个简单的ATM目录结构,开发人员可以快速的了解项目的启动入口,用户层模块,逻辑接口层模块,数据处理模块,日志模块等等。

 

  Python入门之软件开发目录规范

  

  如下的foo项目,就是一个清晰合理的目录结构。

  Python入门之软件开发目录规范

 

   bin:/ 存放项目的一些可执行文件,类似的有script/文件

  foo:/ 存放项目的所有源代码

    1. 源代码中的所有模块、包都改放在这个目录,不能放在顶层目录

    2. 子目录tests/用来存放单元测试代码

    3. 程序的入口一般命名为main.py

  docs:/ 存放一些文档

  setup.py:/ 安装,部署,打包脚本

  requirements.txt: 存放软件依赖的外部Python包列表

  README: 项目说明文件

 

  除此之外,一些开源软件还会有LECENSE.txt, ChangeLog.txt等文件,目录组织和这个类似。

 

三、关于README的内容

 

  README在GITHUB中很常见,一般来说都是必备的。该文件就要简要的介绍该项目的信息,让读者可以快速了解这个项目。

  

  README一般说明以下几个事项:

    1. 软件的定位,软件的基本功能

    2. 运行代码的方法,安装的环境,启动命令

    3. 简要的使用说明

    4. 代码的目录结构说明,可以详细的说明软件的基本原理

    5. 常见问题说明

 

四、关于requirements.txt和setup.py

 

  setup.py 


  一般来说,用setup.py来管理代码的打包、安装、部署问题。业界标准的写法是用Python流行的打包工具setuptools来管理这些事情,这种方式普遍应用于开源项目中。

  不过这里的核心思想不是用标准化的工具来解决这些问题,而是说,一个项目一定要有一个安装部署工具,能快速便捷的在一台新机器上将环境装好、代码部署好和将程序运行起来。

 

  requirements.txt 


  这个文件存在的目的是: 


    1、方便开发者维护软件的包依赖。将开发过程中新增的包添加进这个列表中,避免在setup.py安装依赖时漏掉软件包。 
    2、方便读者明确项目使用了哪些Python包。 


    这个文件的格式是每一行包含一个包依赖的说明,通常是flask>=0.10这种格式,要求是这个格式能被pip识别,这样就可以简单的通过 pip install -r requirements.txt来把所有Python包依赖都装好了。