8.3-写代码必须要写注释吗？（为什么现实中不写注释？）
一、写代码要写注释
“写代码要写注释”自从学编程，这就话就伴随着你。可见注释的重要性。
注释的作用：
- 说明函数的功能
- 说明函数参数的意思
- 说明函数这样设计的原理（计算公式）
- 说明函数的使用场景
- 作者和日期
- 说明变量的作用
- 函数调用方法与注意事项
总之为了能让读这个函数的人明白这个函数的功能，可以注释各种各样的信息。而没有这些注释文字，就不太容易看懂函数的功能与调用用方法。没有注释的情况下，隔一段时间之后，自己也看懂的自己所写函数的功能了。因此，很多书籍、老师、领导、同事、包括你自己，都会告诉你“一定要写注释，不写是万万不能的”。
二、注释标准格式
其实注释没有特别严格的注释格式，但是为了使得注释整齐简洁。还是会有一些格式的要求的。针对不同开发平台，不同编程语言，都有各自不同的注释推荐格式。（高级一些IDE会提供注释快捷键）下面分别列举一些常见的注释格式：
- C#
///
/// 这个方法的作用就是求两个整数之间的最大值
///
/// 第一个整数
/// 第二个整数
/// 返回比较大的那个数字
public static int GetMax(int n1, int n2) {}
- Qt_C++
/*
* @Brief:
* @Param: First
* @Param: Second
* @Return: NULL
*/
void DataManager::SaveValue(int First, int Second) {}
- Java
/**
* This method inputs a number from the user.
* @return The value output as a double.
* @exception IOException On input error.
*/
public double getNumber() throws IOException {}
- 单片机中的C语言（格式1）
/*
******************************************************************************************
* 函 数 名: TMC26X_ReadWriteByte
* 功能说明: TMC26X读写一个字节函数
* 形 参: val写入值
* 返 回 值: 读回状态值
******************************************************************************************
*/
UINT8 TMC26X_ReadWriteByte(UINT8 val)
- 单片机中的C语言（格式2）
/**
* @brief 开始输出指定频率的PWM波
* @param frequency PWM频率 单位:Hz
* @retval 无
*/
void BSP_PwmStart(uint32_t frequency) {}
三、注释类型有哪些？
其实一般没有这个概念，只是本文为了更好的解释说明注释的作用，给分别进行了定义。分别如下：
- 翻译类型注释
- 函数编写背景说明注释
- 实现原理注释
- 编程技术注释
下面编写一个真实的函数来举例说明各种类型的注释：
//此函数用于建立“温度”与“温度传感器电阻”之间的线性关系 //编写背景说明注释
//函数：计算直线公式 //翻译类型注释
//功能：通过2个点来计算出直线方程的k和b //原理类型注释
//参数：w1 第一个温度值，
//参数：z1 第一温度值对应的温度传感器电阻值 //翻译类型注释，把字母翻译成有实际意义的名字
//参数：w2 第二个温度值，
//参数：z2 第二温度值对应的温度传感器电阻值
//参数：k 计算出来的斜率 //翻译类型注释，把一个字母翻译成实际对应的意义
//参数：b 计算出来的截距
//返回值：无 //编程技术注释
void JiSuanZhiXianGongShi( float w1, float z1,
float w2, float z2,
float* k, float* b) {
float temp_k; //临时变量
float temp_b;
//使用到饿直线公式为：y = k*x + b //原理类型注释
//以下代码通过“代入法”分别计算出k和b
temp_k = (z2 - z1) /(w2 - w1);
temp_b = z2 - temp_k * w2;
//通过指针类型形参返回计算结果 //编程技术注释
*k = temp_k;
*b = temp_b;
}
从以上代码注释实例中可以看到，“原理注释”和“背景说明注释”相对来说很重要，如果不写的话，阅读代码的人就看不懂代码。而其余的主要是“翻译类注释”，即把一个字符符号翻译转化为有实际意义的名字（解释其代表的意义）。
四、“其实不用写注释”（^_^哈哈哈）
以上说明文字和例子，充分举例说明了“代码注释”的重要性。但是也许你也发现这样一个现象。在实际编码工作中，大部分人是不写注释的。他们为什么不写。是偷懒吗？
- 嗯，是有偷懒的嫌疑，那么能给出偷懒的理由吗？理由如下：
- 我写的是应用软件代码，有几万行代码等着我写，如果不是重要的注释，我是不写的。因为给每个函数都配一个汉语注释是不现实的。
- 软件开发中，大部分注释是“翻译类型注释”，我只要把函数名字和变量名字起合适了，是不需要再去写啰嗦的注释（我要避免过度注释）
- 切换中文输入法很麻烦，我英语比较好，同事也能看懂。因此我直接用“英语”写函数名字和变量名字即可。不需要写中文注释。
- 写注释之后还要维护注释，否则注释反而造成了错误的引导，所以我干脆不写。
- Linus Torvalds(Linux内核之父)给出的回复是：“Read the fu*king source code”。
- 嗯，以上的理由也挺充分。那么不写注释的代码是什么样子的，别人能看懂吗，请看如下代码。
- 使用英语函数名字和变量名字代替“注释”（注意：仅保留原理类型注释）
void Get_K_B_OfLinearFunction( float temperature1, float resistance1,
float temperature2, float resistance2,
float* k, float* b) {
float temp_k;
float temp_b;
//y = k*x + b
temp_k = (resistance2 - resistance1) /(temperature2 - temperature1);
temp_b = resistance2 - temp_k * temperature2;
*k = temp_k;
*b = temp_b;
}
- 使用合适的“拼音”变量名字代替“注释”（注意：仅保留原理类型注释）
void HuoQuZhiXianFangChengDe_K_B( float wendu1, float dianzu1,
float Wendu2, float dianzu2,
float* k, float* b) {
float temp_k;
float temp_b;
//y = k*x + b
temp_k = (dianzu2 - dianzu1) /(wendu2 - wendu1);
temp_b = dianzu2 - temp_k * wendu1;
*k = temp_k;
*b = temp_b;
}
-
要不要写注释的结论
很显然，这两个函数例子中几乎没有写注释，仅注释了一个“直线方程的公式”。也就是说我们几乎没有“注释可看”，而我们可以看到的是“函数名字”和“参数变量名字”，然后再阅读函数中的代码实现。阅读代码的人可以准确的知道这个函数的真正功能。在理解的同时，还会对代码有一种“切实”的理解。因此调用这个函数的时候可以做到“心知肚明”。而如果只看注释不看代码，在调用函数的时候，就会有个“镜中花，水中月”的一种虚幻的感觉。因此还是的阅读一下函数实现代码。
因此，最终的结论是：
在良好“函数名字”和“变量名字”的辅助下（前提下），是不需要写“注释的”。如果要写，只要写“实现原理类型”和“设计背景说明类型”的注释即可。（另外可以专门去阅读一下大型开源软件的源码，看看大牛们是否写注释）。
五、必须需要写完整注释的特例
- 接口函数
另外要说明一点，在写接口函数的情况下，注释是要求“完完整整”写全的。比如常见的大公司提供的SDK。其中sdk内部实现功能的代码是不必写注释的。但是对外提供的“接口”函数，是必须要完整写注释的（包括函数功能，参数说明，使用方法说明，返回参数说明）。 - 硬件驱动函数（单片机程序代码函数）
由于单片机的代码函数都和硬件紧密相关。函数中经常操作的的是“寄存器”，寄存器一般都是字母缩写。如果不写注释的话，那是真的无法看懂。其次，单片机的代码量相对应用软件来说代码很少，因此给每个函数都配一个中文注释是可接受的。因此要求“单片机”的程序代码都要写注释。