对一套源代码的规范和风格的讨论及优化改进

Posted 2021-03-26 happyyouli

　　我的工程实践是机器学习相关，因此我在GitHub上选了下面的源代码进行学习：https://github.com/WillKoehrsen/machine-learning-project-walkthrough

一、对源代码的分析

　　1、目录结构

　　该源代码使用Python语言，在jupyter notebook上编写。在文件目录下有auto_ml、data、deprecated、images四个文件夹和Machine Learning Project Part 1.ipynb、Machine Learning Project Part 2.ipynb、Machine Learning Project Part 3.ipynb等源代码文件，其中：

　　文件夹auto_ml中存放的是管道程序；

　　文件夹data中存放的是该项目的训练集和测试集等数据压缩包；

　　文件夹deprecated中存放的是对数据进行探索的程序文件；

　　文件夹images中存放的是该项目用到的图像文件。

　　

　　2、代码风格

 　　由于该项目没有使用类，所有暂不讨论类的相关问题。我们随机选取了源代码中的一段个函数实现代码。

　　

• 代码中实现不同功能的部分用空行隔开，并且在前面都有对本段功能描述的注释语句，清晰易懂；
• 函数的命名和变量的命名都采用英文半拼＋英文全拼且用下划线隔开的组合方式，容易理解该函数或变量表达的含义。但是命名并没有采用Python语言推荐的驼峰命名方式，虽然仍然清晰明了，不过还是建议改为驼峰命名方式；
• 代码的缩进和空格的使用都符合Python的规范；
• 由于Jupyter Notebook有独特的代码块编辑方式，可以插入注释说明性的代码块，这样代码的脉络就会更为清晰如下图所示：

　　

　　

　　3、改进建议：

　　

• 如上图第9行代码所示，一行中写了两句代码，这是不规范的行为，建议改为每行一句代码；
• 还有第2部分所描述的变量命名改为驼峰命名方式。

　二、总结同类编程语言或项目在代码规范和风格的一般要求

　　通过对源代码的学习以及相关资料的查阅，下面对python语言的规范和风格做一下总结：

　　1、注释的使用

• 注释的使用在编程中非常重要，因为代码不仅仅是拿来给机器运行的，还是给自己或者别人看的；
• 要用英文写注释；
• 如果一个注释是一个短语或句子，它的第一个单词应该大写，除非它是以小写字母开头的标识符；
• 在修改代码的时候一定要同步更改注释，代码与注释矛盾会给阅读代码带来很大的困扰；
• 尽量使用块注释，少使用行注释；
• 避免没有必要的注释。

　　2、缩进

• 整齐的缩进会使得代码条理清楚，整洁易读；
• 空格是首选的缩进方式，制表符只能用于与同样使用制表符缩进的代码保持一致，Python3不允许同时使用空格和制表符的缩进；
• 每一级缩进使用4个空格。
• 续行应该与其包裹元素对齐，要么使用圆括号、方括号和花括号内的隐式行连接来垂直对齐，要么使用挂行缩进对齐；
• 当使用挂行缩进时，应该考虑到第一行不应该有参数，以及使用缩进以区分自己是续行；
• 每行最大长度79，换行可以使用反斜杠，最好使用圆括号，换行点要在操作符的后边敲回车。

　　3、空格的使用

• 各种右括号前不要加空格；
• 逗号、冒号、分号前不要加空格；
• 函数的左括号前不要加空格。如Func(1)；
• 序列的左括号前不要加空格。如list[2]；
• 操作符左右各加一个空格，不要为了对齐增加空格；
• 函数默认参数的赋值符左右省略空格；
• 不要将多句语句写在同一行，尽管使用‘；’允许；
• if/for/while语句中，即使执行语句只有一句，也必须另起一行。

　　4、命名规范

• 那些暴露给用户的API接口的命名，应该遵循反映使用场景而不是实现的原则
• 永远不要使用字母‘l’（小写的L），‘O’（大写的O），或者‘I’（大写的I）作为单字符变量名。在有些字体里，这些字符无法和数字0和1区分，如果想用‘l’，用‘L’代替；
• 模块应该用简短全小写的名字，如果为了提升可读性，可以用下划线；
• 包命名尽量短小，使用全部小写的方式，不可以使用下划线；
• 类名一般使用首字母大写的约定。在接口被文档化并且主要被用于调用的情况下，可以使用函数的命名风格代替。注意，对于内置的变量命名有一个单独的约定：大部分内置变量是单个单词（或者两个单词连接在一起），首字母大写的命名法只用于异常名或者内部的常量；
• 类的属性（方法和变量）命名使用全部小写的方式，可以使用下划线；
• 因为异常一般都是类，所有类的命名方法也适用于异常。然而需要在异常名后面加上“Error”后缀（如果异常确实是一个错误）；
• 函数名应该小写，如果想提高可读性可以用下划线分隔；
• 始终要将 self 作为实例方法的的第一个参数。始终要将 cls 作为类静态方法的第一个参数；
• 常量通常定义在模块级，通过下划线分隔的全大写字母命名。例如： MAX_OVERFLOW 和 NUM。