8.3-写代码必须要写注释吗?(为什么现实中不写注释?)
一、写代码要写注释
“写代码要写注释”自从学编程,这就话就伴随着你。可见注释的重要性。
注释的作用:
- 说明函数的功能
- 说明函数参数的意思
- 说明函数这样设计的原理(计算公式)
- 说明函数的使用场景
- 作者和日期
- 说明变量的作用
- 函数调用方法与注意事项
总之为了能让读这个函数的人明白这个函数的功能,可以注释各种各样的信息。而没有这些注释文字,就不太容易看懂函数的功能与调用用方法。没有注释的情况下,隔一段时间之后,自己也看懂的自己所写函数的功能了。因此,很多书籍、老师、领导、同事、包括你自己,都会告诉你“一定要写注释,不写是万万不能的”。
二、注释标准格式
其实注释没有特别严格的注释格式,但是为了使得注释整齐简洁。还是会有一些格式的要求的。针对不同开发平台,不同编程语言,都有各自不同的注释推荐格式。(高级一些IDE会提供注释快捷键)下面分别列举一些常见的注释格式:
- C#
/// <summary>
/// 这个方法的作用就是求两个整数之间的最大值
/// </summary>
/// <param name="n1">第一个整数</param>
/// <param name="n2">第二个整数</param>
/// <returns>返回比较大的那个数字</returns>
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和btemp_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内部实现功能的代码是不必写注释的。但是对外提供的“接口”函数,是必须要完整写注释的(包括函数功能,参数说明,使用方法说明,返回参数说明)。 - 硬件驱动函数(单片机程序代码函数)
由于单片机的代码函数都和硬件紧密相关。函数中经常操作的的是“寄存器”,寄存器一般都是字母缩写。如果不写注释的话,那是真的无法看懂。其次,单片机的代码量相对应用软件来说代码很少,因此给每个函数都配一个中文注释是可接受的。因此要求“单片机”的程序代码都要写注释。
8.3-写代码必须要写注释吗?(为什么现实中不写注释?)相关推荐
- 写代码python用什么笔记本好_写代码对电脑有要求吗?什么电脑适合写代码?
这个问题问得好,作为一个一线技术.产品从业者,首先我是一个符合文中定位的最佳用户:然后我从大学期间到现在就帮别人维护电脑超过了千台,这里慢包括了Mac电脑,WindowsPC以及LinuxPC,所以从 ...
- windows下写代码在linux下编译,如何在Windows中编译Linux Unix的代码(采用cygwin)?...
很多经典算法往往是用C++在linux下实现的,对长期从事windows开发的辛苦大众来说,想看这些算法的运行效果不得不费一点小功夫.今天捣鼓了一晚上才搞定这事,写出实现方法和大家共享. 第一步:下载 ...
- 计算机写给未来自己的一段话,现实,致自己 写给自己的霸气一段话汇总73句
1.该来的都会来,该走的全会走,别抗拒,别挽留,别贪恋,别不舍,别担心.学着看淡一些事情,才是对自己最好的保护. 2.不要让未来的你,讨厌现在的自己.我正在努力变成自己喜欢的那个自己.与其祈求生活平淡 ...
- 为什么python注释不能中文_python中输入中文注释是无法编译
在python程序编写时,有时候我们会用中文对程序段进行相应的注释,以增加程序的可读性,但是有时候加了中文注释后,编译时会出现编码无法编译的报错,这是由于编码格式设置不正确的原因. 工具/原料 程序语 ...
- 当我们的代码遇到问题的时候....;要想不遇到问题,写代码的时候要.....
当我们的代码遇到问题的时候: 1,不要怨天怨地.出了问题,当然有可能是系统的bug,API的问题,但是那些几率往往比你犯低级错误的几率要低多了,先从自己身上找原因,是不是自己写错了. 2,要掌握工具. ...
- 读代码比写代码难,真的吗?
关注+星标公众号,不错过精彩内容 来源 | 综合整理知乎内容 上读代码比写代码难,真的吗?来听听别人都怎么说! wsivoky 很多人不明白代码意味着什么,代码意味着要随时理清这一坨: 读代码:找到图 ...
- 在项目中这样写代码的时候,请搭配红花油、跌打损伤酒一起使用
前言 前几天,正巧赶上组里代码review,一下午下来,感觉整个人都血压拉满了.五花八门的代码让我不禁感叹,代码规范这条道路还是任重而道远- 那么今天就来给大家总结一波Java中的代码小技巧,熟练掌握 ...
- 读代码比写代码难,真的?
来源 | 综合整理知乎内容 上读代码比写代码难,真的吗?来听听别人都怎么说! wsivoky 很多人不明白代码意味着什么,代码意味着要随时理清这一坨: 读代码:找到图中两个节点之间的可能路径. 改代码 ...
- 关爱码农成长:关于写代码二三事
2019独角兽企业重金招聘Python工程师标准>>> 工作这么多年以来,一直从事软件相关领域,即使担任主管职务,也一直对技术充满热情.写代码写了这么多年,多少有些体会.我把自己对写 ...
- 用Macbook-苹果系统写代码出现显示问题Text input context does not respond to _valueForTIProperty:
Macbook / 苹果系统写代码出现显示问题 当使用Mac系统,在写代码的时候,如果是有一个GUI显示界面,然后你又去点击这个界面.此时,将报错. 我的源代码,是读取图片,显示图片. import ...
最新文章
- AI,来感受被「分手厨房」支配的恐惧吧!
- 程序员笔试面试基础知识资料整理
- 幻灯片的其他操作(批量生成,重用,版式重设)
- linux子系统led,Linux设备驱动GPIO子系统
- java代码审计ssrf危险函数_某租车系统Java代码审计之后台注入漏洞分析
- 设计模式学习笔记——责任链(Chain of Responsibility)模式
- web前端开发:JavaScript 基本语法,
- 100 - k8s源码分析-准备工作
- 读懂人工智能、机器学习、深度学习、大数据,自然语言处理……
- 数据库设计-逻辑结构设计
- 2022年熔化焊接与热切割题库
- 程序员宝宝们6661儿童节快乐
- 《MATLAB语音信号分析与合成(第二版)》:第5章 带噪语音和预处理
- php echo 后必须die,die 提示的消息都去哪了?
- 【Verilog】parameter
- SunPinyin代码导读-SLM部分
- 视频人像抠图论文阅读
- PHP与memcached实战
- 前端学习(一) body标签(下)
- 基于java的保险业务管理系统的设计与实现
热门文章
- windows 7 桌面图标变白板的问题解决方法
- 魔兽争霸无法在这个计算机,win10魔兽争霸三无法初始化directx怎么办_win10魔兽争霸三不能初始化directx解决步骤...
- 【rfc5506】RTCP mode
- 什么邮箱的归档功能好用?
- nginx+rtmp(或http-flv)+ffmpeg搭建流媒体视频直播服务器
- 压缩文件密码解密工具介绍
- DELL笔记本E5400刷BIOS激活win7
- Captura录屏没有声音解决方法
- 关于内存地址和内存空间的理解
- 为什么计算机使用二进制,你知道吗?