编程习惯 - 注释与文档

说明

• 在编程工作中，程序员清晰的表达自己的思维逻辑是一件很重要的事情，这体现了个人的表达能力，不仅仅是话语表达能力，也是好习惯（注释与文档）。
• 面试中我们更容易关注话语表达能力，但是编程中好习惯更为真实和重要，因为程序员最终的成果是代码而不是空话。

注释

• 在中小公司代码注释起的作用非常大，原因如下：

1. 由于一些原因（程序员很忙，没有多少空闲时间，没有意图），几乎不会有人写文档，在没有文档的情况下代码注释是唯一能帮助程序员理解和掌握代码的工具。
2. 注释几乎和代码绑定在一起，查看最直接，更新也最方便，不像文档需要查找，翻阅。

• 注释有很多作用，如下：

1. 帮助理解逻辑；注释是思维逻辑最直接的体现，因为和代码绑定在一起，相对于文档阅读更方便，查看和理解代码时有助于形成注解。
2. 标注；例如：参数未使用，标注为unused，代码下一步实现标注为TODO等，没有其它方式能够更方便的标志。

• 在敏捷编程思想中，代码+注释即文档。

歧路

• 工作中，由于是中小公司，看到的以及接手的代码很乱，没有固定格式，完全随意书写，注释书写也比较随意，出现一些现象：

1. 注释与代码匹配不上。
2. 注释无意义，例如：a++, 注释为：a加加
3. 复杂逻辑注释太长导致代码排版错乱，显得更乱。

• 个人初始没有标准格式，写不好注释，误认为是注释导致的代码格式混乱，因此没有养成写好注释的习惯。
• 注释的重要性其实大家都知道，只是没有养成好习惯。

文档

• 工作中是否需要写文档，在中小公司存在很多争议。
• 中小公司现状：少有写文档的公司，即使写，也少见完全匹配的。

不想写文档的原因

1. 中小公司，程序员非常忙，根本没有多余时间去写好一份文档，敷衍的文档作用也不大。
2. 简单的任务或者经验丰富的员工，合作或交接比较顺利，文档没起到任何作用，往往弃文档如敝履，程序员不想看文档，认为浪费时间。
3. 程序员表达能力差，文档中全是文字描述或者贴代码，并且表述不清楚。
4. 需要对文档进行管理和持续维护，增加工时，并且容易出现代码和文档不匹配，不匹配的话文档无意义。

想要写文档的原因

1. 团队合作开发，或者工作交接中，很难三言两语说清楚，一般只是将个大概，甚至漏了很多关键点，导致容易出问题，导致成员互相抱怨，影响合作。
2. 一些经验成果，关键的技术，或者研究成果没有文档进行记录，很容易丢失和遗忘。

分析

• 出现以上问题的原因是：大部分公司和程序员将所有文档混为一谈，一种文档没作用就放弃写所有的文档，我们应该区分对待。
• 文档分类：

1. 编程思路以及代码说明文档。
2. 个人经验，关键技术以及研发成果文档。
3. …

• 对于不同文档，我们需要区分对待，例如：编程思路以及代码说明文档很多时候确实没必要写，通过代码和注释就能表述清楚那不是非常完美；但是对于个人经验，关键技术以及研发成果，这些是代码和注释无法体现的，正常应该写一份清晰的文档，并且也不会时长需要修改和维护。

不写文档的处理方法 - 代码即文档

• 对于编程思路以及代码说明，我们通过代码即文档的方式来表述。
• 在命名上尽量体现作用和思路；如果实在无法描述，我们应当在注释里面尽量精简的描述清楚。
• 例如：

1. 头文件中，加上模块说明，函数加上函数使用说明
2. 实现文件(.c, .CPP)中，函数注释加上基本思路，函数名表述函数作用。

写文档的处理方法

• 对于个人经验，关键技术以及研发成果，这些是必须要写文档的，我们尽量将文档写好，描述清楚，描述详细，对以后意义重大。