8.3-写代码必须要写注释吗？（为什么现实中不写注释？）

一、写代码要写注释

“写代码要写注释”自从学编程，这就话就伴随着你。可见注释的重要性。
注释的作用：

• 说明函数的功能
• 说明函数参数的意思
• 说明函数这样设计的原理（计算公式）
• 说明函数的使用场景
• 作者和日期
• 说明变量的作用
• 函数调用方法与注意事项

总之为了能让读这个函数的人明白这个函数的功能，可以注释各种各样的信息。而没有这些注释文字，就不太容易看懂函数的功能与调用用方法。没有注释的情况下，隔一段时间之后，自己也看懂的自己所写函数的功能了。因此，很多书籍、老师、领导、同事、包括你自己，都会告诉你“一定要写注释，不写是万万不能的”。

二、注释标准格式

其实注释没有特别严格的注释格式，但是为了使得注释整齐简洁。还是会有一些格式的要求的。针对不同开发平台，不同编程语言，都有各自不同的注释推荐格式。（高级一些IDE会提供注释快捷键）下面分别列举一些常见的注释格式：

1. C#

/// 

/// 这个方法的作用就是求两个整数之间的最大值
/// 
/// 第一个整数
/// 第二个整数
/// 返回比较大的那个数字
public static int GetMax(int n1, int n2) {}

2. Qt_C++

/*
 * @Brief:  
 * @Param:  First
 * @Param:  Second
 * @Return: NULL
 */
 void DataManager::SaveValue(int First, int Second) {}

3. 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 {}

4. 单片机中的C语言（格式1）

/*
******************************************************************************************
*	函 数 名: TMC26X_ReadWriteByte
*	功能说明: TMC26X读写一个字节函数
*	形    参: val写入值
*	返 回 值: 读回状态值
******************************************************************************************
*/
UINT8 TMC26X_ReadWriteByte(UINT8 val)

5. 单片机中的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;
}

从以上代码注释实例中可以看到，“原理注释”和“背景说明注释”相对来说很重要，如果不写的话，阅读代码的人就看不懂代码。而其余的主要是“翻译类注释”，即把一个字符符号翻译转化为有实际意义的名字（解释其代表的意义）。

四、“其实不用写注释”（^_^哈哈哈）

以上说明文字和例子，充分举例说明了“代码注释”的重要性。但是也许你也发现这样一个现象。在实际编码工作中，大部分人是不写注释的。他们为什么不写。是偷懒吗？

1. 嗯，是有偷懒的嫌疑，那么能给出偷懒的理由吗？理由如下：

• 我写的是应用软件代码，有几万行代码等着我写，如果不是重要的注释，我是不写的。因为给每个函数都配一个汉语注释是不现实的。
• 软件开发中，大部分注释是“翻译类型注释”，我只要把函数名字和变量名字起合适了，是不需要再去写啰嗦的注释（我要避免过度注释）
• 切换中文输入法很麻烦，我英语比较好，同事也能看懂。因此我直接用“英语”写函数名字和变量名字即可。不需要写中文注释。
• 写注释之后还要维护注释，否则注释反而造成了错误的引导，所以我干脆不写。
• Linus Torvalds(Linux内核之父)给出的回复是：“Read the fu*king source code”。

2. 嗯，以上的理由也挺充分。那么不写注释的代码是什么样子的，别人能看懂吗，请看如下代码。

• 使用英语函数名字和变量名字代替“注释”（注意：仅保留原理类型注释）

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;
}

3. 要不要写注释的结论
   很显然，这两个函数例子中几乎没有写注释，仅注释了一个“直线方程的公式”。也就是说我们几乎没有“注释可看”，而我们可以看到的是“函数名字”和“参数变量名字”，然后再阅读函数中的代码实现。阅读代码的人可以准确的知道这个函数的真正功能。在理解的同时，还会对代码有一种“切实”的理解。因此调用这个函数的时候可以做到“心知肚明”。

   而如果只看注释不看代码，在调用函数的时候，就会有个“镜中花，水中月”的一种虚幻的感觉。因此还是的阅读一下函数实现代码。

   因此，最终的结论是：
   在良好“函数名字”和“变量名字”的辅助下（前提下），是不需要写“注释的”。如果要写，只要写“实现原理类型”和“设计背景说明类型”的注释即可。（另外可以专门去阅读一下大型开源软件的源码，看看大牛们是否写注释）。

五、必须需要写完整注释的特例

1. 接口函数
   另外要说明一点，在写接口函数的情况下，注释是要求“完完整整”写全的。比如常见的大公司提供的SDK。其中sdk内部实现功能的代码是不必写注释的。但是对外提供的“接口”函数，是必须要完整写注释的（包括函数功能，参数说明，使用方法说明，返回参数说明）。
2. 硬件驱动函数（单片机程序代码函数）
   由于单片机的代码函数都和硬件紧密相关。函数中经常操作的的是“寄存器”，寄存器一般都是字母缩写。如果不写注释的话，那是真的无法看懂。其次，单片机的代码量相对应用软件来说代码很少，因此给每个函数都配一个中文注释是可接受的。因此要求“单片机”的程序代码都要写注释。