程序员给代码写注释时有哪些讲究?
程序IT圈
共 2541字,需浏览 6分钟
· 2021-02-06
整理/来源丨strongerHuang
如果领导给你一个项目的源码让你阅读,并理解重构代码,但里面一句注释都没有,我想这肯定是之前同事“删库跑路”了。
一般使用 //
或 /* */
,只要统一就好。
2. 说明
//
或 /* */
都可以,但团队要在如何注释及注释风格上确保统一。
2. 说明
3. 文件内容
如果一个 .h
文件声明了多个概念, 则文件注释应当对文件的内容做一个大致的说明, 同时说明各概念之间的联系。一个一到两行的文件注释就足够了, 对于每个概念的详细文档应当放在各个概念中, 而不是文件注释中。
不要在 .h
和 .cc
之间复制注释, 这样的注释偏离了注释的实际意义。
最后再举个最简单的实际例子:
/************************************************************************
*
* Copyright Copyright 2020 Google Inc.
* File Name: 文件名
* Description: 描述
*
* Version: V1.0
* Author: Your_Name
* Create Time: 2020-01-01
*
*************************************************************************/
函数注释
2. 说明
比如:
/************************************************************************
*
* 函 数 名:函数名
* 函数功能:功能描述
* 输入参数:void
* 输出参数:void
* 返 回 值: void
*
* 作 者:Your_Name
* 创建时间:2020-01-01
* 其他说明:无
* 修改信息:无
*
************************************************************************/
不要 从 .h
文件或其他地方的函数声明处直接复制注释. 简要重述函数功能是可以的, 但注释重点要放在如何实现上。
变量注释
2. 说明
全局变量一般作用于多个文件,或者整个工程,因此,其含义相对更复杂,所以在注释的时候,最好描述清楚其具体含义,就是尽量全面描述。
拼写注释
1. 总述
2. 说明
TODO 注释
1. 总述
TODO
注释。TODO
注释要使用全大写的字符串 TODO
, 在随后的圆括号里写上你的名字, 邮件地址, bug ID, 或其它身份标识和与这一 TODO
相关的 issue。主要目的是让添加注释的人 (也是可以请求提供更多细节的人) 可根据规范的 TODO
格式进行查找。添加 TODO
注释并不一定意味着你要自己来修正, 因此当你加上带有姓名的 TODO
时, 一般都是写上自己的名字。结 语
注释固然很重要, 但最好的代码应当本身就是文档,有意义的类型名和变量名, 要远胜过要用注释解释的含糊不清的名字。
你写的注释是给代码阅读者看的, 也就是下一个需要理解你代码的人. 所以慷慨些吧, 下一个读者可能就是你!
PS:欢迎在留言区留下你的观点,一起讨论提高。如果今天的文章让你有新的启发,欢迎转发分享给更多人。 程序IT圈编程交流群已成立 公众号运营至今,离不开小伙伴们的支持。为了给小伙伴们提供一个互相交流的平台,特地开通了官方交流群。扫描下方二维码备注 进群 或者关注公众号 程序IT圈 后获取进群通道。 备注:加群
评论
阿里的同事,写的代码真 TMD 优雅!
通过这篇文章你将了解到整洁的代码对项目、公司和你的重要性,以及如何书写整洁的代码.通过命名、类、函数、测试这四个章节,使我们的代码变得整洁.1、为什么要保持代码整洁?不整洁的代码随着时间的增加而增加时,生产力会随之降低.导致的结果就是:代码不易扩展或扩展容易引发其他问题程序崩溃加班增加公司成本(加人
Java专栏
1
老爸嘲讽我了,写破代码一年就挣十几万,他在工地带50个工人,一个月光人头费就3万,让我滚回去跟他干!
点击上方 "大数据肌肉猿"关注, 星标一起成长点击下方链接,进入高质量学习交流群今日更新| 1052个转型案例分享-大数据交流群来自:网络,侵删有个网友的父亲是做工程的,天天就嘲笑他,说他天天写着破代码有啥用,一年就拿个十多万的死工资,然后告诉他自己在工地里面带了50个工人,一个月能抽三万
程序源代码
0
15种时间序列预测方法总结(包含多种方法代码实现)
向AI转型的程序员都关注了这个号👇👇👇在这篇文章中,我们将深入探讨时间序列预测的基本概念和方法。我们将首先介绍单元预测和多元预测的概念,然后详细介绍各种深度学习和传统机器学习方法如何应用于时间序列预测,包括循环神经网络(RNN)、一维卷积神经网络(1D-CNN)、Transformer、自回归模型(
机器学习AI算法工程
0
中国人民大学《大语言模型》书籍中文版开放下载!还配套代码工具库~
大语言模型综述文章《A Survey of Large Language Models》团队终于出书啦!而且是中文版——《大语言模型》!这本书整理呈现了大模型技术框架和路线图,是一本非常好的入门书籍。🧿🧿🧿
此外,官方不仅发布了电子版 PDF 下载链接,还提供了配套资源。点赞 👍图书下载 → [大
机器学习算法与Python实战
0
网友发问:事业编一年6万,干35年退休挣200万,程序员一年60万,5年就挣300万,事业编再爽能有程序员干五年退休爽?
上一篇:阿里P9被裁,赔偿82w在职场中,我们不可避免地会面临多样的工作机会和选择。然而,如果我们仅将这些不同的工作机会仅以金钱作为衡量标准,那么这种比较就显得过于肤浅和狭隘。一些人可能会通过直接的数学计算来决定哪个职业道路更有利可图,但这种方法忽视了工作的本质、工作量的大小、职业成长的机会,以及经
开发者全社区
0
大厂都在用的 Git 代码管理规范 !
👉 欢迎加入小哈的星球 ,你将获得: 专属的项目实战 / Java 学习路线 / 一对一提问 / 学习打卡 / 赠书福利全栈前后端分离博客项目 2.0 版本完结啦, 演示链接:http://116.62.199.48/ ,新项目正在酝酿中
小哈学Java
2
我想写几个专栏,欢迎大家投票
大家好,我是章北海前段时间更新了一个专栏,阅读和订阅都极不理想,看起来是没有做好调研啊。准备启动新的专栏更新计划了,我有几个选题,看大家更喜欢哪一个呢?欢迎投票,拜谢!
机器学习算法与Python实战
0
这五款牛逼的 IDEA 插件,堪称代码质量检查利器!
来源:blog.csdn.net/a745233700?type=blog一、Alibaba Java Coding Guidelines二、CheckStyle:三、PMD四、FindBugs:五、SonarLint:总结随着业务的发展,系统会越来越庞大,原本简单稳定的功能,可能在不断迭代后复杂度
码农突围
0