个人作业 - Week2 - 代码复审

代码复审Check List

概要部分

• 代码能符合需求和规格说明么？
  
  能完成1~1000000个数独的求解与生成，并能处理异常输入，满足需求。

• 代码设计是否有周全的考虑？
  
  为输入单独开设了一个输入检测类，并考虑了7种参数输入错误的情况以及读入的文件格式错误的情况，代码设计考虑得相当周全。

• 代码可读性如何？
  
  详见可读性。

• 代码容易维护么？
  
  每个类有自己明确分工，各个方法和属性的职责比较明确，代码比较容易维护，若能把功能逻辑部分与输入输出部分代码分离就完美了（详见后期维护建议）。

• 代码的每一行都执行并检查过了吗？
  
  执行并检查过了。

设计规范部分

• 设计是否遵从已知的设计模式或项目中常用的模式？
  
  暂未遵从已知模式。

• 有没有硬编码或字符串/数字等存在？
  
  有，如此处调用trace_back_n()方法
  
  trace_back_n(1,2,n, file);

  然而第一个数固定为题目要求，修改可能性很小，所以对整体代码影 响不大。

• 代码有没有依赖于某一平台，是否会影响将来的移植（如Win32到Win64）？

  • 不依赖某个平台
  • 不影响移植

• 开发者新写的代码能否用已有的Library/SDK/Framework中的功能实现？在本项目中是否存在类似的功能可以调用而不用全部重新实现？
  
  有部分能用基本库函数实现（详见Sudoku::set方法修改建议）。

• 有没有无用的代码可以清除？（很多人想保留尽可能多的代码，因为以后可能会用上，这样导致程序文件中有很多注释掉的代码，这些代码都可以删除，因为源代码控制已经保存了原来的老代码。）
  
  有（详见调试代码清除建议）。

代码规范部分

• 修改的部分符合代码标准和风格么（详细条文略）?
  
  总体挺不错的，只是大括号的使用风格不太一致，如下例

  Sudoku::Sudoku(Sudoku &b)
  {
  	//@overview:copy constructor
  	for (int i = 1; i <= LEN; ++i) {
  		for (int j = 1; j <= LEN; ++j) {
  			board[i][j] = b.board[i][j];
  		}
  	}
  }
  

  方法体使用微软风大括号，而循环体则使用K&R风大括号。

具体代码部分

• 有没有对错误进行处理？对于调用的外部函数，是否检查了返回值或处理了异常？

  • 有对错误的相应处理
  • 调用外部函数有返回值检查

• 参数传递有无错误，字符串的长度是字节的长度还是字符（可能是单/双字节）的长度，是以0开始计数还是以1开始计数？

  • 参数传递无错误
  • 字符串长度为字节的长度
  • 从1开始计数

• 边界条件是如何处理的？Switch语句的Default是如何处理的？循环有没有可能出现死循环？

  • for循环边界条件处理正确
  • 代码中没有出现switch语句
  • 循环不会出现死循环

• 有没有使用断言（Assert）来保证我们认为不变的条件真的满足？
  
  使用了，如下例

  void Sudoku::set(char b[][LEN+1])
  {
  	//@overview:copy a board from b
  	assert(b != NULL);
  	for (int i = 1; i <= LEN; ++i) {
  		for (int j = 1; j <= LEN; ++j) {
  			board[i][j] = b[i][j];
  		}
  	}
  }
  

• 对资源的利用，是在哪里申请，在哪里释放的？有没有可能导致资源泄露（内存、文件、各种GUI资源、数据库访问的连接，等等）？有没有可能优化？
  
  资源释放做得很及时，如下例

  	Sudoku::out[Sudoku::out_pos] = '\0';
  	fstream file(filename, ios::out | ios::app);
  	file << Sudoku::out;
  	delete[] Sudoku::out;
  

• 数据结构中是否有无用的元素？
  
  没有无用元素。

效能

• 代码的效能（Performance）如何？最坏的情况是怎样的？
  
  效能比较好，生成1000000个数独只要11秒。

• 代码中，特别是循环中是否有明显可优化的部分（C++中反复创建类，C#中string的操作是否能用StringBuilder 来优化）？
  
  没有明显可优化部分。

• 对于系统和网络调用是否会超时？如何处理?
  
  不会，代码未涉及系统和网络相关调用。

可读性

• 代码可读性如何？有没有足够的注释？
  
  代码可读性不错，大部分数据结构和方法命名都简洁直观；注释也很充足，还有overview，对后期维护十分友好。

可测试性

• 代码是否需要更新或创建新的单元测试？
  
  大部分代码经过了单元测试，暂无新单元测试必要。

• 还可以有针对特定领域开发（如数据库、网页、多线程等）的核查表。
  
  代码未涉及此类领域。

设计一个代码规范

这里先使用cpplint 1.3.0对个人项目的代码进行检测

• 工具提供的代码规范和你个人的代码风格有什么不同？

  • 工具提供的代码规范要求有Copyright信息（实际为Copyright信息格式与Google style guide上的不符）
  • 一行的字符超过80个
  • 用于注释的双斜杠后未加空格
  • 代码与注释之间至少空两个空格
  • 不能直接使用using namespace std
  • 大括号前未加括号

• 工具提供的代码规范里有哪些部分是你之前没有想到的？

  用于注释的双斜杠后未加空格
  
  代码与注释之间至少空两个空格

  以上两点是我没想到的。

• 为什么要这样规范？这样的规范有意义吗？
  
  这样的规范能提高可读性和统一性。个人认为这样的规范优点是能提高代码维护效率，缺点是会抹杀程序员的个人编码风格。

代码规范整理

风格规范

• 缩进格式：
  
  4个空格

• 行宽：
  
  80个字符

• 左括号位置：
  
  K&R风格

• 命名风格：
  
  小驼峰式命名

• 长语句的换行：
  
  不影响可读性即可

• 指针声明格式：
  
  星号紧挨类型

• 访问修饰符顺序：
  
  public / protected / private

• return之后的表达式是否加圆括号：
  
  必要时才加括号

• 命名空间内代码是否缩进：
  
  不缩进

• 水平留白：
  
  运算符前后留白，函数的参数之间不留白

• 垂直留白：
  
  函数之间留白不超过一行，函数体内留白处加注释

• 注释：
  
  每个函数前加注释

设计规范

• 是否支持goto语句：
  
  不支持

• 是否支持struct：
  
  不支持

• 是否支持运算符重载：
  
  不支持

• 变量定义与初始化是否同时完成：
  
  是