第五章 - 补充内容（软件开发设计规范）

第五章 - 补充内容（软件开发设计规范）

5.16 软件开发规范

什么是开发规范?

为什么要有开发规范呢?

将一个简短的程序放在一个文件中，我们运行他感觉没什么问题，但是当做一个网站或者一个软件时候，代码量是很大的，这个时候我们就需要将不同的功能的代码以模块的形式放在项目中。

软件开发，规范你的项目目录结构，代码规范，遵循PEP8规范等等。

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

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

"项目目录结构"其实也是属于"可读性和可维护性"的范畴，我们设计一个层次清晰的目录结构，就是为了达到以下两点:

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

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

1、配置start.py文件

我们首先要配置启动文件，启动文件很简单就是将项目的启动执行放置start.py文件中，运行start.py文件可以成功启动项目即可。 那么项目的启动就是这个指令run() 我们把这个run()放置此文件中不就行了？

在starts.py找不到run这个变量，肯定是会报错的。NameError: name 'run' is not defined 。

如果我们仅使用简单的import并不能导入该模块，因为模块在这个三个地方：内存，内置，sys.path里面，然而core在内存中肯定是没有的，也不是内置，而且sys.path也不可能有，因为sys.path只会将你当前的目录（bin）加载到内存，只能将core的路径添加到sys.path中，这样就可以了。

import sys
sys.path.append(r'D:\lnh.python\py project\teaching_show\blog\core')

from src import run
run()

这样虽然解决了问题，但是如果我们在其他文件中再次导入模块，又要重新加入文件，这样就产生了重复工作。

我们只要将这个blog项目的工作目录添加到sys.path中，这样无论这个项目中的任意一个文件引用项目中哪个文件，就都可以找到了。

import sys
sys.path.append(r'D:\lnh.python\pyproject\teaching_show\blog')

from core.src import run
run()

通过上述方法虽然能实现减少导入，但是如果我们将项目迁移到其他电脑上，这样你的路径就与迁移过后的路径不一样了，这样我们把路径写死了，所以我们需要使用os来解决：

import sys
import os
# sys.path.append(r'D:\lnh.python\py project\teaching_show\blog')

print(os.path.dirname(__file__))
# 获取本文件的绝对路径  # D:/lnh.python/py project/teaching_show/blog/bin

print(os.path.dirname(os.path.dirname(__file__)))
# 获取父级目录也就是blog的绝对路径  # D:/lnh.python/py project/teaching_show/blog

BATH_DIR = os.path.dirname(os.path.dirname(__file__))
sys.path.append(BATH_DIR)

from core.src import run
run()

还差一个小问题，这个starts文件可以当做脚本文件进行直接启动，如果是作为模块，被别人引用的话，按照这么写，也是可以启动整个程序的，这样合理么？这样是不合理的，作为启动文件，是不可以被别人引用启动的，所以我们此时要想到 __name__了：

import sys
import os
# sys.path.append(r'D:\lnh.python\py project\teaching_show\blog')

# print(os.path.dirname(__file__))

# 获取本文件的绝对路径  # D:/lnh.python/py project/teaching_show/blog/bin

# print(os.path.dirname(os.path.dirname(__file__)))
# 获取父级目录也就是blog的绝对路径  # D:/lnh.python/py project/teaching_show/blog

BATH_DIR = os.path.dirname(os.path.dirname(__file__))
sys.path.append(BATH_DIR)
from core.src import run
​
if __name__ == '__main__':
    run()

2、配置settings.py文件

我们就会将我们项目中的静态路径，数据库的连接设置等等文件放置在settings文件中。

我们看一下，你的主逻辑src中有这样几个变量：

status_dic = {
    'username': None,
    'status': False,
}
flag = True
register_path = r'D:\lnh.python\py project\teaching_show\blog\register'

setttings文件叫做配置文件，其实也叫做配置静态文件，什么叫静态？ 静态就是一般不会轻易改变的，但是对于上面的代码status_dic ，flag这两个变量，由于在使用这个系统时会时长变化，所以不建议将这个两个变量放置在settings配置文件中，只需要将register_path放置进去就可以。

register_path = r'D:\lnh.python\py project\teaching_show\blog\register'

但是你将这个变量放置在settings.py之后，你的程序启动起来是有问题，为什么？

with open(register_path, encoding='utf-8') as f1:
NameError: name 'register_path' is not defined

因为主逻辑src中找不到register_path这个路径了，所以会报错，那么我们解决方式就是在src主逻辑中引用settings.py文件中的register_path就可以了。

这里引发一个问题：为什么你这样写就可以直接引用settings文件呢？我们在starts文件中已经说了，刚已启动blog文件时，我们手动将blog的路径添加到sys.path中了，这就意味着，我在整个项目中的任何py文件，都可以引用到blog项目目录下面的任何目录：bin,conf,core,db,lib,log这几个，所以，刚才我们引用settings文件才是可以的。

3、配置common.py文件

接下来，我们要配置我们的公共组件文件，在我们这个项目中，装饰器就是公共组件的工具，我们要把装饰器这个工具配置到common.py文件中。先把装饰器代码剪切到common.py文件中。这样直接粘过来，是有各种问题的：

所以我们要在common.py文件中引入src文件的这两个变量。

可是你的src文件中使用了auth装饰器，此时你的auth装饰器已经移动位置了，所以你要在src文件中引用auth装饰器，这样才可以使用上。

OK，这样你就算是将你之前写的模拟博客园登录的作业按照规范化目录结构合理的完善完成了，最后还有一个关于README文档的书写。

4、关于README的内容

这个我觉得是每个项目都应该有的一个文件，目的是能简要描述该项目的信息，让读者快速了解这个项目。

它需要说明以下几个事项:

软件定位，软件的基本功能。

运行代码的方法: 安装环境、启动命令等。

简要的使用说明。

代码目录结构说明，更详细点可以说明软件的基本原理。

常见问题说明。

我觉得有以上几点是比较好的一个README。在软件开发初期，由于开发过程中以上内容可能不明确或者发生变化，并不是一定要在一开始就将所有信息都补全。但是在项目完结的时候，是需要撰写这样的一个文档的。

可以参考Redis源码中Readme的写法，这里面简洁但是清晰的描述了Redis功能和源码结构。

5、src.py

这个文件主要存放的就是核心逻辑功能，你看你需要进行选择的这些核心功能函数，都应该放在这个文件中。

6、log文件

log文件就是存储log日志的文件。日志主要是供开发人员使用。比如你项目中出现一些bug问题，比如开发人员对服务器做的一些操作都会记录到日志中，以便开发者浏览，查询。

这样可以把一个项目文件合理的划分成了6个目录文件，