分析一套源代码的代码规范和风格并讨论如何改进优化代码
Posted xujih
tags:
篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了分析一套源代码的代码规范和风格并讨论如何改进优化代码相关的知识，希望对你有一定的参考价值。
- 如无特殊情况, 文件一律使用 UTF-8 编码
- 如无特殊情况, 文件头部必须加入
#-*-coding:utf-8-*-标识 - 统一使用 4 个空格进行缩进
- 这在查看 side-by-side 的 diff 时很有帮助
- 方便在控制台下查看代码
- 太长可能是设计有缺陷
- 自然语言 使用双引号
"..."
例如错误信息；很多情况还是 unicode，使用u"你好世界" - 机器标识 使用单引号
‘...‘
例如 dict 里的 key - 正则表达式 使用原生的双引号
r"..." - 文档字符串 (docstring) 使用三个双引号
"""......""" - 模块级函数和类定义之间空两行；
- 类成员函数之间空一行；
- 可以使用多个空行分隔多组相关的函数
- 函数中可以使用空行分隔出逻辑相关的代码
- 文件使用 UTF-8 编码
- 文件头部加入
#-*-conding:utf-8-*-标识 - import 语句应该分行书写
- import语句应该使用 absolute import
- import语句应该放在文件头部，置于模块说明及docstring之后，于全局变量之前；
- import语句应该按照顺序排列，每组之间用一个空行分隔
- 导入其他模块的类定义时，可以使用相对导入
- 如果发生命名冲突，则可使用命名空间
- 在二元运算符两边各空一格
[=,-,+=,==,>,in,is not, and]: - 函数的参数列表中，
,之后要有空格 - 函数的参数列表中，默认值等号两边不要添加空格
- 左括号之后，右括号之前不要加多余的空格
- 字典对象的左括号之前不要多余的空格
- 不要为对齐赋值语句而使用的额外空格
- 所有的公共模块、函数、类、方法，都应该写 docstring 。私有方法不一定需要，但应该在 def 后提供一个块注释来说明。
- docstring 的结束"""应该独占一行，除非此 docstring 只有一行。
-
在代码的关键部分(或比较复杂的地方), 能写注释的要尽量写注释
- 比较重要的注释段, 使用多个等号隔开, 可以更加醒目, 突出重要性
- 文档注释以 """ 开头和结尾, 首行不换行, 如有多行, 末行必需换行, 以下是Google的docstring风格示例
- 不要在文档注释复制函数定义原型, 而是具体描述其具体内容, 解释具体参数和返回值等
- 对函数参数、返回值等的说明采用numpy标准, 如下所示
-
文档注释不限于中英文, 但不要中英文混用
-
文档注释不是越长越好, 通常一两句话能把情况说清楚即可
- 模块、公有类、公有方法, 能写文档注释的, 应该尽量写文档注释
我的工程实践题目是语音识别，我在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、编码
2、代码格式
2.1、缩进
2.2、行宽
每行代码尽量不超过 80 个字符(在特殊情况下可以略微超过 80 ，但最长不得超过 120)
理由：
2.3、引号
简单说，自然语言使用双引号，机器标示使用单引号，因此 代码里 多数应该使用 单引号
2.4、空行
2.5、编码
3、import 语句
4、空格
5、换行
Python 支持括号内的换行。这时有两种情况。
1) 第二行缩进到括号的起始处
2) 第二行缩进 4 个空格，适用于起始括号就换行的情形
使用反斜杠换行，二元运算符+ .等应出现在行末；长字符串也可以用此法换行
禁止复合语句，即一行中包含多个语句：
6、docstring
docstring 的规范中最其本的两点：
二、注释
1、注释
1.1、块注释
“#”号后空一格，段落件用空行分开（同样需要“#”号）
1.2、行注释
至少使用两个空格和语句分开，注意不要使用无意义的注释
1.3、建议
2、文档注释（Docstring）
作为文档的Docstring一般出现在模块头部、函数和类的头部，这样在python中可以通过对象的__doc__对象获取文档.
编辑器和IDE也可以根据Docstring给出自动提示.
命名规范
模块：尽量使用小写命名，首字母保持小写，尽量不要用下划线(除非多个单词，且数量不多的情况)
类名：使用驼峰(CamelCase)命名风格，首字母大写，私有类可用一个下划线开头；将相关的类和顶级函数放在同一个模块里. 不像Java, 没必要限制一个类一个模块.
函数：函数名一律小写，如有多个单词，用下划线隔开；私有函数在函数前加一个下划线 “_”
变量：变量名尽量小写, 如有多个单词，用下划线隔开；
常量：常量采用全大写，如有多个单词，使用下划线隔开
python代码规范和命名规范转自 http://www.imooc.com/article/19184?block_id=tuijian_wz#child_5_1
以上是关于分析一套源代码的代码规范和风格并讨论如何改进优化代码的主要内容，如果未能解决你的问题，请参考以下文章