C++学习(c++17)——3.1. 注释的必要性
这个周末沉迷书籍，把面向对象的一系列思想又看了看。感觉还是记成博客比较好，因为对自己的记忆力没什么信息。这章来谈谈编码风格和注释。
原帖地址： https://www.cnblogs.com/ranbom/
博主LeoRanbom
只在原帖地址的博客上发布，其他地方看到均为爬取。
如果觉得不错希望来点个赞。
前言
编码风格，注释。这俩东西我记得从进入实验室之前的考核就一直有提，进入实验室后，班长还专门给19级的新生们开了一课来专门的讲注释的作用。直到上周因为小程序而给实验室的大家介绍前端时候，也提到了注释的重要性。**But**，注释在我心中也就是有着：不写以后自己也看不懂自己的代码、别人没有注释基本看不懂自己的代码的标签的工具。或者说它也就只是在我心中有这样的印象，但具体效果和规范，因为没有涉及到，我都还是不太清楚。
而编码风格，最早是因为我的缩进啊，格式啊，丑的一比而被前辈们吐槽。后来在做一个小程序——学生管理系统的时候，又被某吴氏学长吐槽C风格的程序。
良好外观的重要性
团队需求
团队是在不断更新的。如果一个新的程序员在一年后不得不使用你的代码，那么你有信心让你的代码能被别人看懂么？就不说别人了，很多人可能自己一年后都看不懂了。那么团队整体会因此拉下多少进度，如果你不能及时提供帮助给那个新程序员的话，那么一个清晰明了的代码结构和注释都是不错的措施。
良好的代码风格
我在学习C++之余，也有用c++写一写自己感兴趣的游戏服务器的拓展。在一个不算大的开源社区里，我也是接触了一些人的代码，有一些实在是很对我的胃口，很清晰明了，容易理解。但与此同时，也有一些看半天看不懂的（我在群里吐槽了一下，那个大佬似乎绝望一般的自嘲：是么，我的代码已经被别人看不懂了233）。
为代码编写文档
编程中，文档通常情况指源文件的注释。注释用来说明一些不能通过阅读代码而得到的信息。
注释来说明用途
很多情况下注释会被用来说明方法或类的用途。
举一个很形象的例子，有一个数据库对象，它有saveRecord()和openDatabase()2个方法。而只有在openDatabase()之后才能使用saveRecord()方法，否则抛出异常。这时候就可以用一个注释
/*
* 此方法如果在openDatabase()没有被调用前调用
* 则抛出异常"DatabaseNotOpenedException"
*/
int saveRecord(Record& record);
C++中强制要求给方法安一个返回类型，但这种返回值无法说明实际代表了什么。（这里返回int实际上是一种不良的设计决策）。这里返回int，但很明显其他人不知道这个int代表什么，因此可以有以下注释:
/*
* Return: int
* 一个代表保存存档的ID的整数
* Throws:
* DatabaseNotOpenedException if the openDatabase() method not been called yet
*/
再详细一点，则可以加上对函数功能的描述和参数的形容。
/*
* saveRecord()
*
* Saves given record to the database
*
* Parameters:
* Record& record: the record to save to the database.
* Return: RecordID
* 一个代表保存存档的ID的整数
* Throws:
* DatabaseNotOpenedException if the openDatabase() method not been called yet
*/
RecordID saveRecord(Record& record);
这里还可以吧泛型int替换成int的类型别名RecordID，如上面这块代码所示。但同时注释里面也要表明这些参数或者返回值的具体形式。
注释来解释复杂代码
这点应该很好解释，对于学算法的人来说。经常一些很简单的语句，可以完成一个复杂的算法，但如果没有解释或者提前接触过，我觉得我是在看天书。在此不加叙述。
注释来传递元信息
元信息，包括文件的作者、创建日期、提供的特性、某bug的编号、提醒可能有的问题、修改日志、版权声明.etc.
注释的风格
下面阐述我见到的3种注释，并且说明其必要性（自我感觉）：
1.每行都加入注释
每行代码后面都加入注释，或者每隔一行代码中间加1行或者多行注释。这样给人一种是在编程之外写故事的感觉。但是在一些非常难以理解的局部代码中，这是必要的。
2.前置注释
有写team可能会决定在每个源文件以某种标准注释作为开头。可能会有:
- 最近的修改日期
- 原始作者
- 前面所讲的修改日志
- 文件给出的功能ID
- 版权信息
- 文件或类的简要说明
- 未完成的功能
- 已知的bug
有些开发环境可能还允许创建模板来更规范地填写元数据的注释
3.固定格式的注释
在java中有javaDoc工具来为项目创建超文本文档来更好地查阅类和对象的功能。而C++，则有Doxygen可以解析注释，来自动生成类似的HTML文档、类图或者其他什么。
4.特殊注释
- 尽量避免使用冒犯性或令人反感的语言，因为你不知道有谁会看你的代码（西语中黑色的negro，万一一个非裔程序员看到了会怎么样）
- 一些无伤大雅的内部玩笑是可以的，但要让项目管理人看看是否合适。
- 看看能不能通过修改变量名之类的操作来避免多余的注释。
- 处理不太明显的API时，应解释对其引用。
- 更新代码后记得更新注释。
- 与其用注释把代码分为小部分，不如思考一下能不能用直接把代码分割开来。(也就是自动化文档，self-documenting)
总结
最终还是要说，优秀的代码本身就容易阅读，而注释只需要提供有用的附加信息。
