C语言的注释要注意几点

点击蓝字

840f0337d8d2c886048a539cafa81686.png

关注我们

如果领导给你一个项目的源码让你阅读,并理解重构代码,但里面一句注释都没有,我想这肯定是之前同事“删库跑路”了。

看一份源码什么很重要?除了各种代码规范之外,还有一个比较重要的就是注释。

注释虽然写起来很痛苦, 但对保证代码可读性至关重要,下面的将描述如何注释以及在哪儿注释。

注释风格

1.总述

一般使用 // 或 /* */,只要统一就好。

2.说明

// 或 /* */ 都可以,但 //  常用,要在如何注释及注释风格上确保统一。

文件注释

1.总述

在每一个文件开头加入版权、作者、时间等描述。

文件注释描述了该文件的内容,如果一个文件只声明,或实现,或测试了一个对象,并且这个对象已经在它的声明处进行了详细的注释,那么就没必要再加上文件注释,除此之外的其他文件都需要文件注释。

2.说明

法律公告和作者信息:

每个文件都应该包含许可证引用. 为项目选择合适的许可证版本(比如, Apache 2.0, BSD, LGPL, GPL)。

如果你对原始作者的文件做了重大修改,请考虑删除原作者信息。

3.文件内容

如果一个 .h 文件声明了多个概念, 则文件注释应当对文件的内容做一个大致的说明, 同时说明各概念之间的联系. 一个一到两行的文件注释就足够了, 对于每个概念的详细文档应当放在各个概念中, 而不是文件注释中。

不要在 .h 和 .cc 之间复制注释, 这样的注释偏离了注释的实际意义。

函数注释

1.总述

函数声明处的注释描述函数功能; 定义处的注释描述函数实现。

2.说明

函数声明:

基本上每个函数声明处前都应当加上注释, 描述函数的功能和用途. 只有在函数的功能简单而明显时才能省略这些注释(例如, 简单的取值和设值函数)。

比如:FreeRTOS创建任务函数申明:

3af753b54872cdd705cfe01742910bea.png

函数定义:

如果函数的实现过程中用到了很巧妙的方式, 那么在函数定义处应当加上解释性的注释。比如, 你所使用的编程技巧, 实现的大致步骤, 或解释如此实现的理由. 举个例子, 你可以说明为什么函数的前半部分要加锁而后半部分不需要。

不要 从 .h 文件或其他地方的函数声明处直接复制注释. 简要重述函数功能是可以的, 但注释重点要放在如何实现上。

变量注释

1.总述

通常变量名本身足以很好说明变量用途, 某些情况下, 也需要额外的注释说明。

2.说明

根据不同场景、不同修饰符,变量可以分为很多种类,总的来说变量分为全局变量、局部变量。

一般来说局部变量仅限于局部范围,其含义相对简单容易理解,只需要简单注释即可。

全局变量一般作用于多个文件,或者整个工程,因此,其含义相对更复杂,所以在注释的时候,最好描述清楚其具体含义,就是尽量全面描述。

(提示:全局变量尽量少用)

拼音注释

1.总述

可能一个变量、一个函数包含的意思非常复杂,需要多个单词拼写而成,此时对拼写内容就需要详细注释。

2.说明

注释的通常写法是包含正确大小写和结尾句号的完整叙述性语句. 大多数情况下, 完整的句子比句子片段可读性更高. 短一点的注释, 比如代码行尾注释, 可以随意点, 但依然要注意风格的一致性。

同时,注释中的拼写、逗号也很重要。虽然被别人指出该用分号时却用了逗号多少有些尴尬, 但清晰易读的代码还是很重要的. 正确的标点, 拼写和语法对此会有很大帮助

TODO 注释

1.总述

对那些临时的, 短期的解决方案, 或已经够好但仍不完美的代码使用 TODO 注释。

TODO 注释要使用全大写的字符串 TODO, 在随后的圆括号里写上你的名字, 邮件地址, bug ID, 或其它身份标识和与这一 TODO 相关的 issue. 主要目的是让添加注释的人 (也是可以请求提供更多细节的人) 可根据规范的 TODO 格式进行查找. 添加 TODO 注释并不意味着你要自己来修正, 因此当你加上带有姓名的 TODO 时, 一般都是写上自己的名字。

最后

注释固然很重要, 但最好的代码应当本身就是文档,有意义的类型名和变量名, 要远胜过要用注释解释的含糊不清的名字。

你写的注释是给代码阅读者看的, 也就是下一个需要理解你代码的人. 所以慷慨些吧, 下一个读者可能就是你!

*声明:本文于网络整理,版权归原作者所有,如来源信息有误或侵犯权益,请联系我们删除或授权事宜。

1810f2dc3656116b7dcaf3e59a6c6ca3.png

07cd96ccb75030ca716d808b6bda7d70.gif

戳“阅读原文”我们一起进步

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/news/337729.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

java自动推断类型_推断:Facebook的新Java静态分析工具

java自动推断类型如何使用Facebook的Infer改善Java开发工作流程? 如果您与技术话题保持同步(如果您正在阅读此博客,我想您会这样做),那么您可能听说过Facebook 刚刚向公众发布的新工具:推断。 由于它来自F…

android官方架构组件,Android 架构组件官方文档01——LifeCycle

使用生命周期感知组件处理生命周期支持生命周期的组件执行操作以响应另一个组件(例如Activity和fragment)的生命周期状态更改。这些组件可帮助您生成组织性更好,并且通常更轻量的代码,这些代码更易于维护。常见的模式是在Activity和fragment的生命周期方…

C语言的核心和灵魂

点击蓝字关注我们提起C语言大部分开发者很自然就会想到指针二字,没错,作为C的核心和灵魂,它的地位咱们就不再赘述了。今天我们想跟大家讲的是指针中的两个特有名词:“悬空指针”和“野指针”。悬空指针C语言中的指针可以指向一块内…

javaone_JavaOne 2015 –提交技巧和建议

javaone大家都知道JavaOne 。 感觉就像一直存在。 而且,即使我们跌宕起伏,而地理位置也不是我们想要的那样,旧金山也很昂贵,而且和。 这是有关各种Java的顶级会议。 今年又再次成为程序委员会(“ Java,DevO…

C语言_结构体总结,附实例源码

点击蓝字关注我们当前文章介绍动态堆空间内存分配与释放,C语言结构体定义、初始化、赋值、结构体数组、结构体指针的相关知识点,最后通过一个学生管理系统综合练习结构体数组的使用。1. 动态内存管理C语言代码----->编译----->链接------>可执行…

四大C语言知识总结

点击蓝字关注我们1、#define宏定义以#号开头的都是编译预处理指令,它们不是C语言的成分,但是C程序离不开它们,#define用来定义一个宏,程序在预处理阶段将用define定义的来内容进行了替换。因此在程序运行时,常量表中并…

jdbc select语句_SELECT语句使用JDBC和Hibernate批量获取

jdbc select语句介绍 现在,我已经介绍了Hibernate对INSERT , UPDATE和DELETE语句的批处理支持,是时候分析SELECT语句结果集的批量提取了。 JDBC ResultSet提供了一个客户端Proxy游标,用于获取当前语句的返回数据。 执行该语句后&…

看懂开源项目,你得熟悉这几个 C++11 新特性

点击蓝字关注我们C11 中增加了许多的新特性。在本文中,我们来聊一下 lambda 表达式,闭包,std::function以及std::bind。lambda 表达式C11 中新增了 lambda 表达式这一语言特性。lambda 表达式可以让我们快速和便捷的创建一个 “函数”。下面是…

5元素升级android6,【五元素ifive X.7】无障碍升级,ifveX详细升级固件教程,快为爱机升级吧。...

android系统的乐趣就是可以随意的刷机,所以拿到如此高配置的ifiveX也是想随时体验最新的android系统。而很多朋友可能只会用设备,刷机这种比较技术性的动作就不太会弄了。也就在这周,才帮同事刷RUU把已经无法启动的G12刷了回来。所以刷机还是…

昆仑通态复制的程序可以用吗_昆仑通态专题(七):MCGS组态软件的设备窗口...

点击上方蓝色字体,关注我们设备窗口是MCGS嵌入版组态软件系统的重要组成部分,在设备窗口中建立系统与外部硬件设备的连接关系,使系统能够从外部设备读取数据并控制外部设备的工作状态,实现对工业过程设备的实时监控与操作。01 设备…

嵌入式C语言程序调试和宏使用的技巧

点击蓝字关注我们01.调试相关的宏在Linux使用gcc编译程序的时候,对于调试的语句还具有一些特殊的语法。gcc编译的过程中,会生成一些宏,可以使用这些宏分别打印当前源文件的信息,主要内容是当前的文件、当前运行的函数和当前的程序…

matlab中欠定方程组超定方程组_《数值天气预报》:球坐标系中的基本方程组

人们是如何预报天气的?目前的预报方法主要有两种:一种是基于由各种探测资料绘制的天气图,结合历史资料进行分析预测;另一种是基于大气方程组,利用数值解法对其进行求解,从而得到未来时刻的大气状态。后者就…

浏览器总是跳转到缓存界面_跳转到企业缓存之前要考虑的事项

浏览器总是跳转到缓存界面介绍 关系数据库事务是ACID ,强大的一致性模型简化了应用程序开发。 由于启用Hibernate缓存是一项配置 ,因此,只要数据访问层开始出现性能问题,就转向缓存非常吸引人。 添加缓存层确实可以提高应用程序性…

CryptoTab 服务器_如何架设FTP服务器,如何架设FTP服务器,具体架设方法

FTP服务器,则是在互联网上提供存储空间的计算机,它们依照FTP协议提供服务。 FTP的全称是File Transfer Protocol(文件传输协议)。顾名思义,就是专门用来传输文件的协议。简单地说,支持FTP协议的服务器就是FTP服务器。那么&#xf…

C语言和C++的区别和联系

点击蓝字关注我们C语言和C到底是什么关系?首先C和C语言本来就是两种不同的编程语言,但C确实是对C语言的扩充和延伸,并且对C语言提供后向兼容的能力。对于有些人说的C完全就包含了C语言的说法也并没有错。C一开始被本贾尼斯特劳斯特卢普&#…

hibernate语句_如何优化Hibernate EllementCollection语句

hibernate语句介绍 Hibernate支持三种数据映射类型 : 基本 (例如String,int), Embeddable和Entity 。 通常,数据库行被映射到Entity ,每个数据库列都与一个基本属性相关联。 当将多个字段映射组…

C++ 虚函数表剖析

点击蓝字关注我们一、概述为了实现C的多态,C使用了一种动态绑定的技术。这个技术的核心是虚函数表(下文简称虚表)。本文介绍虚函数表是如何实现动态绑定的。二、类的虚表每个包含了虚函数的类都包含一个虚表。我们知道,当一个类&a…

aix pax_通过Pax考试对JBoss Fuse 6.x进行集成测试,第一部分

aix paxJBoss Fuse是一个功能强大的分布式集成平台,具有内置功能,可用于针对集成的微服务部署进行集中式配置管理,服务发现,版本控制,API网关,负载平衡,故障转移等。 JBoss Fuse 6.x构建在Fabri…

android王者调不了界面,王者荣耀登录界面怎么改?登录界面更改教程[多图]

王者荣耀登录界面怎么改?许多玩家都想更改自己登陆的界面,但是都不清楚,下面就让安卓乐园小编为大家带来,登录界面更改教程。王者荣耀登录界面怎么改?1、安卓手机打开文件管理,找到根目录下Android/data/co…

y空间兑换代码_Python爬虫实战:QQ空间全自动点赞工具

QQ空间自动点赞前景提要目标确定分析介绍登陆获取cookie寻找XML寻找可变参数获取第一个空间动态寻找点赞所需的URL寻找可变参数功能提升到秒赞全部代码最后还是希望你们能给我点一波小小的关注。奉上自己诚挚的爱心私信小编01即可获取大量Python学习资料前景提要因为我周围的小…