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

Posted 2020-11-15 zzydexiaowu

我的工程训练做的是手写汉字识别，在GitHub上下载了一套与课题相关的源码进行分析，来分析它的代码风格和规范：

在源代码目录结构、文件名/类名/函数名/变量名等命名、接口定义规范和单元测试组织形式等方面的做法和特点：

这个项目是用python完成的项目，所以将项目文件导入至pycharm软件中进行管理，下面是项目代码在pycharm下目录结构：

 

 

如上图所示，该项目文件目录结构层次清晰，命名规范，符合要求；

 

 

如上图所示，文件名/类名/函数名/变量名等命名符合以下规则：

1.数字不可以开头

2.不可以使用关键字 例如：class就不可以，因为class是关键字。

3.不可以包含“_、$”以外的特殊符号，例如：“DemoTest”就不可以，其中的空格就是特殊符号。

 

 

如上图所示，接口定义规范：

在Python中接口由抽象类和抽象方法去实现，接口是不能实例化的，只能被别的类继承去实现相应的功能。函数封装了功能实现，调用时给出指定参数即可，部分参数给出默认参数，缺省时可按默认值传入。直接将功能封装在函数内部，调用函数传递指定参数即可实现。

4.单元测试组织形式

单元测试就是让开发者编写一小段代码，检验目标代码的功能是否符合预期。组织方法形式有：自上而下法、自下而上法、分离法等。

通常情况下，单元测试主要面向一些功能单一的模块进行。所以在此项目中，每当实现一部分功能，就要自上而下地测试该部分代码能否实现规定的要求。

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

 

 

 

如图所示，该项目代码符合代码规范的有：

 

1.命名规范

 

命名可读性强，函数以及类和变量的命名没有使用拼音与英文混合的方式，也没有直接使用中文的方式，对于其功能和用途能够清晰读懂，符合代码规范。

 

2.缩进规范

 

代码整体的排版缩进看起来清晰规整，符合代码规范。

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

如上图所示，不符合“代码的简洁、清晰、无歧义”的基本原则的有：

1.注释不规范规范

注释内容少，没有准确描述代码含义不符合代码规范。

2.可读性差

如上图所示，该项目的代码可读性差，每行代码超长，一下一大坨，让人眼花缭乱，不符合代码规范。

 

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

 

1.排版

 

1-1：程序块要采用缩进风格编写，缩进的空格数为4个。

 

1-2：相对独立的程序块之间、变量说明之后必须加空行。

1-3：不允许把多个短语句写在一行中，即一行只写一条语句。

1-4：对齐只使用空格键，不使用TAB键。

1-5：函数或过程的开始、结构的定义及循环、判断等语句中的代码都要采用缩进风格，case语句下的情况处理语句也要遵从语句缩进要求。

2 .注释

2-1：一般情况下，源程序有效注释量必须在20％以上。

2-2：文件头部应进行注释，注释必须列出：版权说明、版本号、生成日期、作者、内容、功能、修改日志等。

2-3：函数头部应进行注释，列出：函数的目的/功能、输入参数、输出参数、返回值、调用关系（函数、表）等。

2-4：边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性。不再有用的注释要删除。

2-5：注释的内容要清楚、明了，含义准确，防止注释二义性。

3. 标识符命名

3-1：标识符的命名要清晰、明了，有明确含义，同时使用完整的单词或大家基本可以理解的缩写，避免使人产生误解。

3-2：命名中若使用特殊约定或缩写，则要有注释说明。

3-3：自己特有的命名风格，要自始至终保持一致，不可来回变化。

3-4：对于变量命名，禁止取单个字符（如i、j、k...），建议除了要有具体含义外，还能表明其变量类型、数据类型等，但i、j、k 作局部循环变量是允许的。

3-5：除非必要，不要用数字或较奇怪的字符来定义标识符。

3-6：在同一软件产品内，应规划好接口部分标识符（变量、结构、函数及常量）的命名，防止编译、链接时产生冲突。

3-7：用正确的反义词组命名具有互斥意义的变量或相反动作的函数等。

4. 可读性

4-1：注意运算符的优先级，并用括号明确表达式的操作顺序，避免使用默认优先级。

4-2：避免使用不易理解的数字，用有意义的标识来替代。

4-3：源程序中关系较为紧密的代码应尽可能相邻。

4-4：不要使用难懂的技巧性很高的语句，除非很有必要时。

以上这些做法符合代码规范和风格一般要求以及同类编程语言或项目在代码规范和风格的一般要求。