我的工程实践是机器学习相关，因此我在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。
原文地址：https://www.cnblogs.com/happyyouli/p/11660931.html
时间： 2024-08-30 11:45:26