分析一套源代码的代码规范和风格并讨论如何改进优化代码

标签：提前   必须   公有   资料   部分   ide   识别   diff   限制   

我的工程实践题目是语音识别，我在GitHub上找到了一个star数较高的相关项目，地址是：   https://github.com/Uberi/speech_recognition   感兴趣的同学也可以去clone一份体验一下。

接下来对代码代码规范和风格进行分析，先看一下它的目录结构

各个文件夹、文件的作用在github上都有说明，

.github  不太清楚干嘛用的，里面没什么有用的文件，就一个ISSUE_TEMPLATE.md文件

examples  示例文件

reference  参考资料

speech_recognition  主要文件夹

tests  测试文件

third-party  第三方的一些包

 对于文件夹得命名还是很符合GitHub的一些规范，接下来看看类名/函数名/变量名等命名

对于类名的命名符合驼峰(CamelCase)命名风格，每个单词的首字母大写。

然后是类中的方法。

这是一个类中的一些函数，同样很规范，采用了下划线法命名，看函数名就可以知道用途，看起来又整洁。

python中变量不需要提前定义，变量赋值也不需要类型声明，我们随便选几个来看一下

类中变量的命名同样符合下划线法命名。

在这个项目中同样存在不符合规范的代码，比如这个

一行代码过长，影响代码阅读。对于这种情况，应该用 “ \ ” 符号换行。

对于用python写代码的代码规范和命名规范

代码规范

1、编码

• 如无特殊情况, 文件一律使用 UTF-8 编码
• 如无特殊情况, 文件头部必须加入#-*-coding:utf-8-*-标识

2、代码格式

2.1、缩进

• 统一使用 4 个空格进行缩进

2.2、行宽

每行代码尽量不超过 80 个字符(在特殊情况下可以略微超过 80 ，但最长不得超过 120)

理由：

• 这在查看 side-by-side 的 diff 时很有帮助
• 方便在控制台下查看代码
• 太长可能是设计有缺陷

2.3、引号

简单说，自然语言使用双引号，机器标示使用单引号，因此 代码里 多数应该使用 单引号

• 自然语言 使用双引号 "..."
  例如错误信息；很多情况还是 unicode，使用u"你好世界"
• 机器标识 使用单引号 ‘...‘
  例如 dict 里的 key
• 正则表达式 使用原生的双引号 r"..."
• 文档字符串 (docstring) 使用三个双引号 """......"""

2.4、空行

• 模块级函数和类定义之间空两行；
• 类成员函数之间空一行；
• 可以使用多个空行分隔多组相关的函数
• 函数中可以使用空行分隔出逻辑相关的代码

2.5、编码

• 文件使用 UTF-8 编码
• 文件头部加入#-*-conding:utf-8-*-标识

3、import 语句

• import 语句应该分行书写

• import语句应该使用 absolute import

• import语句应该放在文件头部，置于模块说明及docstring之后，于全局变量之前；
• import语句应该按照顺序排列，每组之间用一个空行分隔

• 导入其他模块的类定义时，可以使用相对导入

• 如果发生命名冲突，则可使用命名空间

4、空格

• 在二元运算符两边各空一格[=,-,+=,==,>,in,is not, and]:

• 函数的参数列表中，,之后要有空格

• 函数的参数列表中，默认值等号两边不要添加空格

• 左括号之后，右括号之前不要加多余的空格

• 字典对象的左括号之前不要多余的空格

• 不要为对齐赋值语句而使用的额外空格

5、换行

Python 支持括号内的换行。这时有两种情况。

1) 第二行缩进到括号的起始处

2) 第二行缩进 4 个空格，适用于起始括号就换行的情形

使用反斜杠\换行，二元运算符+ .等应出现在行末；长字符串也可以用此法换行

禁止复合语句，即一行中包含多个语句：

6、docstring

docstring 的规范中最其本的两点：

1. 所有的公共模块、函数、类、方法，都应该写 docstring 。私有方法不一定需要，但应该在 def 后提供一个块注释来说明。
2. docstring 的结束"""应该独占一行，除非此 docstring 只有一行。

二、注释

1、注释

1.1、块注释

“#”号后空一格，段落件用空行分开（同样需要“#”号）

1.2、行注释

至少使用两个空格和语句分开，注意不要使用无意义的注释

1.3、建议

• 在代码的关键部分(或比较复杂的地方), 能写注释的要尽量写注释

• 比较重要的注释段, 使用多个等号隔开, 可以更加醒目, 突出重要性

2、文档注释（Docstring）

作为文档的Docstring一般出现在模块头部、函数和类的头部，这样在python中可以通过对象的__doc__对象获取文档.
编辑器和IDE也可以根据Docstring给出自动提示.

• 文档注释以 """ 开头和结尾, 首行不换行, 如有多行, 末行必需换行, 以下是Google的docstring风格示例
• 不要在文档注释复制函数定义原型, 而是具体描述其具体内容, 解释具体参数和返回值等
• 对函数参数、返回值等的说明采用numpy标准, 如下所示

• 文档注释不限于中英文, 但不要中英文混用

• 文档注释不是越长越好, 通常一两句话能把情况说清楚即可

• 模块、公有类、公有方法, 能写文档注释的, 应该尽量写文档注释

命名规范

模块：尽量使用小写命名，首字母保持小写，尽量不要用下划线(除非多个单词，且数量不多的情况)

类名：使用驼峰(CamelCase)命名风格，首字母大写，私有类可用一个下划线开头；将相关的类和顶级函数放在同一个模块里. 不像Java, 没必要限制一个类一个模块.

函数：函数名一律小写，如有多个单词，用下划线隔开；私有函数在函数前加一个下划线 “_”

变量：变量名尽量小写, 如有多个单词，用下划线隔开；

常量：常量采用全大写，如有多个单词，使用下划线隔开

python代码规范和命名规范转自 http://www.imooc.com/article/19184?block_id=tuijian_wz#child_5_1

分析一套源代码的代码规范和风格并讨论如何改进优化代码

标签：提前   必须   公有   资料   部分   ide   识别   diff   限制   

原文地址：https://www.cnblogs.com/xujih/p/11657626.html