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

Posted 2021-03-26 baozhw

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

我做的项目是基于语音识别的人工智能问答系统，在GitHub上找了一套代码

 

源代码分析：

目录结构

 

命名合理，格式规范。

 

代码分析

选取其中一个函数分析。可以看到在变量命名、函数命名方面符合规范要求，仅有部分运算符号两侧未全部加空格。最后的return语句行过长，超过80字符应当分行。

 

块注释部分简洁明了，重点突出。导入部分应当每行导入一个模块，最好不要一行传入多个。

 

代码书写一般规范：

代码格式

     1.统一使用 4 个空格进行缩进

     2.每行代码尽量不超过 80 个字符(在特殊情况下可以略微超过 80 ，但最长不得超过 120)

     3.自然语言使用双引号，机器标示使用单引号，文档字符串 (docstring) 使用三个双引号

     4.模块级函数和类定义之间空两行，类成员函数之间空一行；

 

注释

     1.块注释： “#”号后空一格，段落件用空行分开（同样需要“#”号）

     2.行注释： 至少使用两个空格和语句分开，注意不要使用无意义的注释，在代码的关键部分(或比较复杂的地方), 能写注释的要尽量写注释 比较重要的注释段, 使用多个等号隔开, 可以更加醒目, 突出重要性

     3.文档注释（Docstring）：不要在文档注释复制函数定义原型, 而是具体描述其具体内容, 解释具体参数和返回值等。

     4.作为文档的Docstring一般出现在模块头部、函数和类的头部，这样在python中可以通过对象的__doc__对象获取文档. 编辑器和IDE也可以根据Docstring给出自动提示. 文档注释以 """ 开头和结尾, 首行不换行, 如有多行, 末行必需换行

     5.文档注释不限于中英文, 但不要中英文混用 文档注释不是越长越好, 通常一两句话能把情况说清楚即可 模块、公有类、公有方法, 能写文档注释的, 应该尽量写文档注释

 

命名规范

    1.模块尽量使用小写命名，首字母保持小写，尽量不要用下划线

    2.类名使用驼峰(CamelCase)命名风格，首字母大写，私有类可用一个下划线开头‘’_‘’

       将相关的类和顶级函数放在同一个模块里. 不像Java, 没必要限制一个类一个模块.

    3.函数名一律小写，如有多个单词，用下划线隔开

       私有函数在函数前加一个下划线‘’_‘’

    4.变量名尽量小写, 如有多个单词，用下划线隔开

       常量采用全大写，如有多个单词，使用下划线隔开