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

Posted 2022-12-27 wzh711

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

  由于我的工程实践题目是《基于大数据问答训练的中文自然语言理解系统设计》，所以我选用了一套python实现语音识别的代码。

 ·目录结构如下图所示：

           

 

      可见其文件及文件夹的命名与其功能相关，较为规范。

     ·类名/函数名/变量名等命名

          

                              

 

   如上图所示类名、函数名、变量名都与其功能相关，便于理解，较为规范。

 ·接口定义规范和单元测试组织形式

  在Python中接口由抽象类和抽象方法去实现，同Java不同Python没有类继承的限制，接口是不能被实例化的，只能被别的类继承去实现相应的功能。此程序中Listener类和Speaker类都是抽象类其中都定义了很多抽象方法，比如：get_google_translation()、writer()等，都可以在主程序中很容易的通过import导入类，并通过构造对象访问类中的方法。

  单元测试有很多方法，比如：自上而下法、自下而上法、分离法等。本程序使用自上而下法较为合理，因为主程序功能的实现需要用到所有的底层模块。

 

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

       该程序文件、类、方法等的命名较为规范，注释也较为完备，从而让代码的可读性大大增加。

 

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

       该程序中有些地方的注释缩进有问题，方法的定义中有一些没必要出现的空格和不规范的换行。方法与方法之间有的地方间隔太近，容易看混淆。有些变量的命名较为随意，让人难以理解。注释的位置较为随意，有的低方甚至有些杂乱无章，从而让代码显得不是太简洁明了。通过解决以上问题，可以让本代码更符合“简洁、清晰、无歧义”的基本原则，具备较强的可维护性。

 

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

       下面我总结一下Python的代码规范和风格的一般要求：

 

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

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

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

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

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

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

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

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

   ·每行不超过80个字符。

   ·宁缺毋滥的使用括号。

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

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

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

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

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

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

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

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

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

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

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