标签：功能   tab   规范   代码   document   代码结构   风格   发布   生成   

这个周末沉迷书籍，把面向对象的一系列思想又看了看。感觉还是记成博客比较好，因为对自己的记忆力没什么信息。这章来谈谈编码风格和注释。

LeoRanbom的博客

原帖地址： 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)

总结

最终还是要说，优秀的代码本身就容易阅读，而注释只需要提供有用的附加信息。

C++学习(c++17)——3.1. 注释的必要性

标签：功能   tab   规范   代码   document   代码结构   风格   发布   生成   

原文地址：https://www.cnblogs.com/ranbom/p/12685425.html