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

Posted happyyouli

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了对一套源代码的规范和风格的讨论及优化改进相关的知识,希望对你有一定的参考价值。

  我的工程实践是机器学习相关,因此我在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。

以上是关于对一套源代码的规范和风格的讨论及优化改进的主要内容,如果未能解决你的问题,请参考以下文章

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

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

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

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

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

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