软件目录结构规范

软件目录结构规范

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

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

  1. 一类同学认为,这种个人风格问题"无关紧要"。理由是能让程序work就好,风格问题根本不是问题。
  2. 另一类同学认为,规范化能更好的控制程序结构,让程序具有更高的可读性。

我是比较偏向于后者的,因为我是前一类同学思想行为下的直接受害者。我曾经维护过一个非常不好读的项目,其实现的逻辑并不复杂,但是却耗费了我非常长的时间去理解它想表达的意思。从此我个人对于提高项目可读性、可维护性的要求就很高了。"项目目录结构"其实也是属于"可读性和可维护性"的范畴,我们设计一个层次清晰的目录结构,就是为了达到以下两点:

  1. 可读性高: 不熟悉这个项目的代码的人,一眼就能看懂目录结构,知道程序启动脚本是哪个,测试目录在哪儿,配置文件在哪儿等等。从而非常快速的了解这个项目。
  2. 可维护性高: 定义好组织规则后,维护者就能很明确地知道,新增的哪个文件和代码应该放在什么目录之下。这个好处是,随着时间的推移,代码/配置的规模增加,项目结构不会混乱,仍然能够组织良好。

所以,我认为,保持一个层次清晰的目录结构是有必要的。更何况组织一个良好的工程目录,其实是一件很简单的事儿。

目录组织方式

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

这里面说的已经很好了,我也不打算重新造轮子列举各种不同的方式,这里面我说一下我的理解和体会。

假设你的项目名为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

简要解释一下:

  1. bin/: 存放项目的一些可执行文件,当然你可以起名script/之类的也行。
  2. foo/: 存放项目的所有源代码。(1) 源代码中的所有模块、包都应该放在此目录。不要置于顶层目录。(2) 其子目录tests/存放单元测试代码; (3) 程序的入口最好命名为main.py
  3. docs/: 存放一些文档。
  4. setup.py: 安装、部署、打包的脚本。
  5. requirements.txt: 存放软件依赖的外部Python包列表。
  6. README: 项目说明文件。

除此之外,有一些方案给出了更加多的内容。比如LICENSE.txt,ChangeLog.txt文件等,我没有列在这里,因为这些东西主要是项目开源的时候需要用到。如果你想写一个开源软件,目录该如何组织,可以参考这篇文章。

下面,再简单讲一下我对这些目录的理解和个人要求吧。

关于README的内容

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

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

  1. 软件定位,软件的基本功能。
  2. 运行代码的方法: 安装环境、启动命令等。
  3. 简要的使用说明。
  4. 代码目录结构说明,更详细点可以说明软件的基本原理。
  5. 常见问题说明。

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

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

关于requirements.txt和setup.py

setup.py

一般来说,用setup.py来管理代码的打包、安装、部署问题。业界标准的写法是用Python流行的打包工具setuptools来管理这些事情。这种方式普遍应用于开源项目中。不过这里的核心思想不是用标准化的工具来解决这些问题,而是说,一个项目一定要有一个安装部署工具,能快速便捷的在一台新机器上将环境装好、代码部署好和将程序运行起来。

这个我是踩过坑的。

我刚开始接触Python写项目的时候,安装环境、部署代码、运行程序这个过程全是手动完成,遇到过以下问题:

  1. 安装环境时经常忘了最近又添加了一个新的Python包,结果一到线上运行,程序就出错了。
  2. Python包的版本依赖问题,有时候我们程序中使用的是一个版本的Python包,但是官方的已经是最新的包了,通过手动安装就可能装错了。
  3. 如果依赖的包很多的话,一个一个安装这些依赖是很费时的事情。
  4. 新同学开始写项目的时候,将程序跑起来非常麻烦,因为可能经常忘了要怎么安装各种依赖。

setup.py可以将这些事情自动化起来,提高效率、减少出错的概率。"复杂的东西自动化,能自动化的东西一定要自动化。"是一个非常好的习惯。

setuptools的文档比较庞大,刚接触的话,可能不太好找到切入点。学习技术的方式就是看他人是怎么用的,可以参考一下Python的一个Web框架,flask是如何写的: setup.py

当然,简单点自己写个安装脚本(deploy.sh)替代setup.py也未尝不可。

requirements.txt

这个文件存在的目的是:

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

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

 

关于配置文件的使用方法

注意,在上面的目录结构中,没有将conf.py放在源码目录下,而是放在docs/目录下。

很多项目对配置文件的使用做法是:

  1. 配置文件写在一个或多个python文件中,比如此处的conf.py。
  2. 项目中哪个模块用到这个配置文件就直接通过import conf这种形式来在代码中使用配置。

这种做法我不太赞同:

  1. 这让单元测试变得困难(因为模块内部依赖了外部配置)
  2. 另一方面配置文件作为用户控制程序的接口,应当可以由用户自由指定该文件的路径。
  3. 程序组件可复用性太差,因为这种贯穿所有模块的代码硬编码方式,使得大部分模块都依赖conf.py这个文件。

所以,我认为配置的使用,更好的方式是,

  1. 模块的配置都是可以灵活配置的,不受外部配置文件的影响。
  2. 程序的配置也是可以灵活控制的。

能够佐证这个思想的是,用过nginx和mysql的同学都知道,nginx、mysql这些程序都可以自由的指定用户配置。

所以,不应当在代码中直接import conf来使用配置文件。上面目录结构中的conf.py,是给出的一个配置样例,不是在写死在程序中直接引用的配置文件。可以通过给main.py启动参数指定配置路径的方式来让程序读取配置内容。当然,这里的conf.py你可以换个类似的名字,比如settings.py。或者你也可以使用其他格式的内容来编写配置文件,比如settings.yaml之类的。

转载于:https://www.cnblogs.com/PYlog/p/8697047.html

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/news/367457.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

软件工程的基本步骤

1问题定义 问题定义阶段必须回答的关键问题:“要解决的问题是什么?”如果不知道问题是什么就试图解决这个问题,显然是盲目的,只会白白浪费时间和金钱,最终得出 的结果很可能是毫无意义的。尽管确切地定义问…

matlab norm函数使用_matlab norm(a-b)

(示例: X(1:10,1:10)zeros(10,10),LX[X,X;X,X]) Matlab 中冒号(: )的使用方法小结: (1)用于生成向量,a:b,一般要求 a一、matlab 基本操作 Matlab 概率论与数理统计 1. ...概率密度函数 1 (1) 均匀分布:unifpdf(x,a,b)...{X 3}, p1normcdf(5,3,2)- normcdf(2,3,......[A B];rank…

解决MyEclipse JAVA EE无法识别Base64问题

第一步:右击项目选择Build Path,选择Configure Build Path第二步:点击JRE System Library选择右边的Edit第三步:选择Alternate JRE,点击Install JREs第四步:移出原有的MyEclipse自带的 JRE,(选中后点击remove&#xff…

JavaFX的响应式设计

使用CSS技术,为您的网站创建响应式设计相对容易。 根据屏幕的大小,您可以使用其他CSS文件和布局。 在JavaFX中,乍一看这似乎有点困难,因为CSS仅负责样式,而不负责布局。 但是,为各个屏幕尺寸使用不同的FXML…

用Vue Node从零开始实现拼多多前后端商城项目 — 记录踩坑之旅(上篇)

前言 本人移动端开发妹子工程师一枚 ,因为公司项目需要用到前端的技术(主要是vue),自己自学了一段时间,最近花了半个月在工作之余的时间终于自己完完整整写下来一整个前后端商城项目(当然是跟了一个线上项目直播班,不要嘲笑我)&am…

python自动补全库_这个库厉害了,自动补全Python代码,节省50%敲码时间

近日,Reddit 上的一篇帖子引起了网友的热议。帖子作者「mlvpj」称:「我们使用深度学习完成了一个简单的项目,可以自动进行 Python 代码补全。」根据介绍,该项目基于 LSTM 模型,训练后,负责对代码的缺失部分…

matlab 小波 cdd,[Matlab] 单导联心电数据的小波(包)消噪及压缩

% 用小波(包)对MitbihCmprTstExample_08730_01(软硬阈值)进行消噪与压缩clear all;clc;close all;disp(用小波(包)对MitbihCmprTstExample_08730_01(软硬阈值)进行消噪和压缩);load MitbihCmprTstExample_08730_01.mat;countlength(sig);xsig(:,1); ysig(:,2); zsig(:,3);TSx(2…

系统重装助手教你如何在Microsoft Edge中恢复“关闭所有选项卡”警告

在Microsoft Edge中,当您打开多个选项卡时,浏览器将显示“您要关闭所有选项卡吗?” 警告,以防止您意外关闭重要标签。 通常,在没有第二个想法的情况下,您会立即禁用此功能,检查提示中的“始终关…

受JAAS保护的JAX-RS端点

随着RESTFUL(JAX-RS)作为创建Web服务端点的“首选”方式的问世,很长一段时间以来,我一直想知道人们如何围绕它实现安全机制。 归根结底,我假设JAX-RS的基础实现是servlet,因此其安全性也可能围绕容器&…

es springboot 不设置id_springboot整合ES_文档ID删除

1.本课程涵盖**SpringBoot2.x版本10个常用技术点适应企业开发要求,学习IDEA开发工具下的SpringBoot2.x开发学习SpringBoot2.x - 基于Restful接口开发规范学习SpringBoot2.x - 官方推荐模版引擎 - Thymeleaf开发学习SpringBoot2.x - MockMVC测试学习SpringBoot2.x - …

前端必须懂的计算机网络知识—(跨域、代理、本地存储)

前端必须懂的计算机网络知识系列文章: DNS服务器和跨域问题计算机网络的分层模型IP地址和MAC地址前端必须懂的计算机网络知识—(跨域、代理、本地存储)前端必须懂的计算机网络知识—(TCP)前端必须懂的计算机网络知识—(HTTP)前端必须懂的计算机网络知识—(XSS、CSR…

axios请求报Uncaught (in promise) Error: Request failed with status code 404

使用axios处理请求时,出现的问题解决 当url是远程接口链接时,会报404的错误: Uncaught (in promise) Error: Request failed with status code 404 解决方法: var instance axios.create({ headers: {content-type: application/…

php canvas 前端JS压缩,获取图片二进制流数据并上传

<?php if(isset($_GET[upload]) && $_GET[upload] img){//二进制数据流$data file_get_contents ( php://input ); // 不需要php.ini设置&#xff0c;内存压力小if(empty($data)){$data gzuncompress ( $GLOBALS [HTTP_RAW_POST_DATA] ); // 需要php.ini设…

如何给linux目录加密码,怎么只给一个文件夹的内容加密?

该楼层疑似违规已被系统折叠 隐藏此楼查看此楼Encfs security information ││ ││ According to a security audit by Taylor Hornby (Defuse Security), the ││ current implementation of Encfs is vulnerable or potentially vulnerable ││ to multiple types of att…

cordova监听事件中调用其他方法_Laravel模型事件的实现原理详解

模型事件在 Laravel 的世界中&#xff0c;你对 Eloquent 大多数操作都会或多或少的触发一些模型事件&#xff0c;下面这篇文章主要给大家介绍了关于Laravel模型事件的实现原理&#xff0c;文中通过示例代码介绍的非常详细&#xff0c;需要的朋友可以参考借鉴。前言Laravel的ORM…

MongoDB和Web应用程序

当今时代是数据大规模增长的时代。 数据存储不是问题&#xff0c;是的&#xff0c;但是结构化和存储的方式可能会增加或减少所需数据块的查找时间。 不断增长的非结构化数据的用例 脸书&#xff1a; 7.5亿用户处于活跃状态&#xff0c;三分之一的互联网用户拥有Facebook帐户 …

【译】10个有趣的JSCSS库(2018.10)

Tutorialzine每月都会给我们精心挑选优秀的web开发资源&#xff0c;这些资源可以帮助我们解锁最新和最炫酷的网络开发姿势。前端er,让我们一起先睹为快吧&#xff01; WatermelonDB WatermelonDB是用于构建React和React Native应用程序的下一代数据库。快速&#xff0c;高度可…

自定义分页器

好久没来写东西那&#xff01;今天写个自定义分页器给大家参考下吧 首先我们在自己创建的Django项目的app下新建一个utils文件夹&#xff0c;用来放我们的分页器组件 简单说下分页器实现原理&#xff1a; 1.利用ORM查询语句的限制数据条数来确定每页显示的数据 2.设置我们每页显…

五 Vue学习 首页学习 (上)

首页&#xff1a; http://localhost:8002/#/&#xff0c; 登录页面如下&#xff1a; index.js文件中如下的路由配置&#xff0c;转过去看login.vue是如何实现的。 const routes [ { path: /, component: login },&#xff08;这里一个问题&#xff1a; logi…

linux下mqm添加用户,Linux 下MQ的安装和配置亲测

开篇之前奉上几条黄金链接&#xff1a;MQ参考文档http://publib.boulder.ibm.com/infocenter/wmqv7/v7r0m0/index.jsp?topic%2Fcom.ibm.mq.doc%2Fhelp_home_wmq.htmhttp://www-01.ibm.com/support/docview.wss?uidswg27006467MQ下载地址&#xff1a;http://www-03.ibm.com/so…