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

Posted 2021-05-07 fengyakk

我的工程实践课题是《手写中文汉字识别》，涉及深度学习与神经网络方面的知识，因此这里我找了一份对路透社数据集进行文本分类的源码，对其代码规范和风格进行讨论。

1.结合工程实践选题相关的一套源代码，根据其编程语言或项目特点，分析其在源代码目录结构、文件名/类名/函数名/变量名等命名、接口定义规范和单元测试组织形式等方面的做法和特点

源码结构如下：

（由于图片太长没法全部截屏，我用python写了一个拼接的小程序分两次截屏然后拼起来了）

代码中导入的库有tensorflow、keras、numpy和 matplotlib，这都是一些常用的库。其中keras框架是以tensorflow为后端运行的。

文件名/类名/函数名/变量名等命名

文件名：文件名是我自己命名的，没有实际意义。

类名：这个源代码中并没有定义类，不过在python中，类是面对对象编程中重要的概念，一般定义类的格式为：

class 类名：

   def __init__(self):

      self.属性=...

   def 方法(self,...):

      ......

和C++中类的定义相似，但更加简单明了。

函数名：这份源代码中只定义了一个函数vectorize_sequences()，其他都是调用库中的函数，比如“reuters.load_data()、reuters.get_word_index()、model.add()、plt.show()”等等。

变量名：这份源代码中的变量格外的多，但为了读代码的人更容易理解，取得名字会尽量一目了然，比如“train_data[10]、train_labels[10]、model、x_val、y_val、val_loss”等等，看到变量名就可以猜到用途。

接口定义规范和单元测试组织形式等方面的做法和特点

在python中接口主要的途径就是导入，所以这里分析在python语言中导入的规范。可见这里导入的接口都写在了源代码的最前面，导入应该按照从最通用到最不通用的顺序分组:

1.标准库导入

2.第三方库导入

3.应用程序指定导入

在python中，对单个文件进行测试的方法就是利用main函数，因此，代码应该在执行主程序前总是检查 if name == ‘main‘ , 这样当别的模块被导入时主程序就不会被执行。

 

 2.列举哪些做法符合代码规范和风格一般要求

由于本文源代码是使用python书写的，因此在这里主要基于python语言的书写规范和风格写一写：

Python语言规范

　　1. imports 仅仅用做包和模块的导入，包的导入每个尽量独占一行

　　2. packages 导入模块尽量使用模块的全路径

　　3. Exceptions 必须小心使用

　　4. Global variables 避免使用全局变量

　　5. Generator 

　　6. lambda 函数仅仅适用于一行代码能实现的简单函数

　　7. True or False 尽量使用[],‘‘,{},0,None来隐式表示False

Python风格规范　

　　1、代码编排

　　　　1 缩进：4个空格实现缩进，尽量不使用Tab，禁止混用Tab和空格

　　　　2 行：每行最大长度不超过79，换行可以使用反斜杠()。最好使用圆括号将换行内容括起来，不建议使用“;”

　　　　3 空行：类和top-level函数定义之间空两行；类中的方法定义之间空一行；函数内逻辑无关段落之间空一行；其他地方尽量不要再空行。

　　　　4 空格：括号内的第一个位置，不要空格。紧靠右括号的位置也不要空格。冒号(:)、逗号(,)、分号(;)之前不要加空格。切片木有参数，不要加空格等

　　　　5 括号：对于单元素tuple一定要加,和括号

　　2、命名规范

　　　　module_name

　　　　package_name  

　　　　ClassName  

　　　　method_name  

　　　　ExceptionName

　　　　function_name

　　　　GLOBAL_CONSTANT_NAME

　　　　global_var_name

　　　　instance_var_name

　　　　function_parameter_name

　　　　local_var_name

　　3、注释规范

　　　　

　　　　1.块注释，在一段代码前增加的注释。在‘#’后加一空格。段落之间以只有‘#’的行间隔。比如：

　　　　# Description : Module config. 　　　　# 　　　　# Input : None 　　　　# 　　　　# Output : None

　　　　2. 行注释，在一句代码后加注释。比如：x = x + 1 # Increment x 但是这种方式尽量少使用。

　　　　3. 避免无谓的注释。

　　4、编程建议

　　　　1. 字符串拼接，尽量使用join。使用str的方法而不是内置方法。使用startswith或endswith拉检查前缀和后缀

　　　　2. 单例对象，尽量使用is 、is not，不要使用==

　　　　3. 使用is not而不是not is

　　　　4. 使用def来定义函数，而不是将匿名函数赋给某个变量

　　　　5. 尽量使代码整齐，简洁

　　　　6. 使用isinstance()来判断instance的类型

 

3.列举哪些做法有悖于“代码的简洁、清晰、无歧义”的基本原则，及如何进一步优化改进

对于python代码来说，缩进的使用是非常重要的，合理使用缩进也使得代码看起来简洁明了，但缩进使用的不正确就会导致代码产生歧义从而出错。优化可以通过单步调试程序来进行。

 

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

对于python程序而言：

 

   ·仅对包和模块使用导入，即模块间共享代码的重用机制，命名空间管理约定十分简单. 每个标识符的源都用一种一致的方式指示. x.Obj表示Obj对象定义在模块x中.

   ·使用模块的全路径名来导入每个模块，避免模块名冲突. 查找包更容易。

   ·允许使用异常, 但必须小心。通过使用异常，我们可以在错误发生的时候继续执行与这个错误无关的余下代码，维持程序的正常运行。

   ·避免使用全局变量，即定义在模块级的变量，因为导入时可能会改变模块行为。

   ·鼓励使用嵌套/本地/内部类或函数。

   ·使用单行函数时推荐使用条件表达式，简化if语句。

   ·构建函数时鼓励使用默认值。

   ·不要在行尾加分号, 也不要用分号将两条命令放在同一行。

   ·每行不超过80个字符。

   ·宁缺毋滥的使用括号。

   ·用4个空格来缩进代码，即悬挂缩进，此时第一行不应有参数。

   ·顶级定义之间空两行, 方法定义之间空一行。比如类定义之间应该空两行。

   ·按照标准的排版规范来使用标点两边的空格。一个函数必须要有文档字符串比如：在逗号、分号后加空格；一般表达式在等号的两端加空格；括号里不要有空格等。

   ·确保对模块, 函数, 方法和行内注释使用正确的风格。比如：一个函数应该要有注释，包含函数做什么, 以及输入和输出的详细描述。对于块注释（#）和行注释（""" """）的使用，也要细心考量。

   ·最后着重说一下命名的规范：

    1）“Internal”表示仅模块内可用, 或者, 在类内是保护或私有的.

    2）用单下划线“_”开头表示模块变量或函数是protected的(使用from xxx import *时不会包含在内).

    3）用双下划线“__”开头的实例变量或方法表示它是private的.

    4）将相关的类和顶级函数放在同一个模块里。

    5）对类名使用大写字母开头的单词(如Car), 但是模块名应该用小写加下划线的方式(如speed)。

    6）应避免：单字符名称（除了计数器和迭代器）；包/模块名中的连字符“-”；双下划线开头并结尾的名称。