如果领导给你一个项目的源码让你阅读,并理解重构代码,但里面一句注释都没有,我想这肯定是之前同事“删库跑路”了。
一般使用 //
或 /* */
,只要统一就好。
2. 说明
//
或 /* */
都可以,但团队要在如何注释及注释风格上确保统一。
2. 说明
3. 文件内容
如果一个 .h
文件声明了多个概念, 则文件注释应当对文件的内容做一个大致的说明, 同时说明各概念之间的联系。一个一到两行的文件注释就足够了, 对于每个概念的详细文档应当放在各个概念中, 而不是文件注释中。
不要在 .h
和 .cc
之间复制注释, 这样的注释偏离了注释的实际意义。
最后再举个最简单的实际例子:
2. 说明
比如:
不要 从 .h
文件或其他地方的函数声明处直接复制注释. 简要重述函数功能是可以的, 但注释重点要放在如何实现上。
2. 说明
全局变量一般作用于多个文件,或者整个工程,因此,其含义相对更复杂,所以在注释的时候,最好描述清楚其具体含义,就是尽量全面描述。
1. 总述
2. 说明
1. 总述
TODO
注释。TODO
注释要使用全大写的字符串 TODO
, 在随后的圆括号里写上你的名字, 邮件地址, bug ID, 或其它身份标识和与这一 TODO
相关的 issue。主要目的是让添加注释的人 (也是可以请求提供更多细节的人) 可根据规范的 TODO
格式进行查找。添加 TODO
注释并不一定意味着你要自己来修正, 因此当你加上带有姓名的 TODO
时, 一般都是写上自己的名字。注释固然很重要, 但最好的代码应当本身就是文档,有意义的类型名和变量名, 要远胜过要用注释解释的含糊不清的名字。
你写的注释是给代码阅读者看的, 也就是下一个需要理解你代码的人. 所以慷慨些吧, 下一个读者可能就是你!
<p style="font-family: -apple-system-font, system-ui, "Helvetica Neue", "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei UI", "Microsoft YaHei", Arial, sans-serif;letter-spacing: 0.544px;white-space: normal;caret-color: rgb(51, 51, 51);"><span style="font-size: 15px;"><strong>程序员GitHub</strong>,现已正式上线!</span><br /></p><p style="font-family: -apple-system-font, system-ui, "Helvetica Neue", "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei UI", "Microsoft YaHei", Arial, sans-serif;letter-spacing: 0.544px;white-space: normal;caret-color: rgb(51, 51, 51);"><br /></p><p style="font-family: -apple-system-font, system-ui, "Helvetica Neue", "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei UI", "Microsoft YaHei", Arial, sans-serif;letter-spacing: 0.544px;white-space: normal;caret-color: rgb(51, 51, 51);"><span style="font-size: 15px;">接下来我们将会在该上,专注为大家分享GitHub上有趣的开源库包括Python,Java,Go,前端开发等优质的学习资源和技术,分享一些程序员圈的新鲜趣事。</span></p>
<section mpa-paragraph-type="ignored" data-mpa-template="t"><section><section data-role="outer" label="Powered by 135editor.com"><section data-tools="135编辑器" data-id="91525"><section><section><section data-role="outer" label="Powered by 135editor.com"><section data-tools="135编辑器" data-id="91525"><section><section data-mpa-template="t" mpa-paragraph-type="ignored"><section data-mpa-template="t" mpa-paragraph-type="ignored"><section data-mpa-template="t" mpa-paragraph-type="ignored"><h1><section data-role="paragraph"><section data-width="100%"><section><section><section><section><section powered-by="xiumi.us"><section><section powered-by="xiumi.us"><section><section><section data-mpa-template="t" mpa-from-tpl="t" style="color: rgb(62, 62, 62);letter-spacing: 0.544px;white-space: pre-wrap;widows: 1;word-spacing: 2px;caret-color: rgb(51, 51, 51);"><section data-mpa-template="t" mpa-from-tpl="t"><section data-mpa-template="t" mpa-from-tpl="t"><section><span style="color: rgb(0, 122, 170);"><strong><span style="letter-spacing: 0.1em;orphans: 4;">推荐阅读:</span></strong></span></section><p><br /></p><section style="line-height: 2em;">这个GitHub 1400星的Git魔法书火了,斯坦福校友出品丨有中文版</section><section style="line-height: 2em;">贼 TM 好用的 Java 工具类库<br /></section><section style="line-height: 2em;">超全Python IDE武器库大总结,优缺点一目了然!<br /></section><section style="line-height: 2em;">秋招来袭!GitHub28.5颗星!这个汇聚阿里,腾讯,百度,美团,头条的面试题库必须安利!<br /></section><section style="line-height: 2em;">收获10400颗星!这个Python库有点黑科技,竟然可以伪造很多'假'的数据!<br /></section><section style="line-height: 2em;"><span style="color: var(--weui-LINK);-webkit-tap-highlight-color: rgba(0, 0, 0, 0);cursor: pointer;font-size: 15px;">牛掰了!这个Python库有点逆天了,竟然能把图片,视频无损清晰放大!</span><br /></section><p><br /></p></section></section></section></section></section></section></section></section></section></section></section></section></section></section></h1><h1 style="white-space: pre-wrap;letter-spacing: 0.544px;font-family: 微软雅黑;"><section mpa-from-tpl="t"><pre style="letter-spacing: 0.544px;word-spacing: 1px;line-height: inherit;"><pre style="letter-spacing: 0.544px;line-height: inherit;"><section data-mpa-template="t" mpa-from-tpl="t"><section data-id="94086" data-color="#276ca3" data-tools="135编辑器" mpa-from-tpl="t"><section><section mpa-from-tpl="t"><pre style="color: rgb(63, 63, 63);letter-spacing: 0.544px;line-height: inherit;"><section data-mpa-template="t" mpa-from-tpl="t"><section data-id="94086" data-color="#276ca3" data-tools="135编辑器" mpa-from-tpl="t"><section><section mpa-from-tpl="t" style="display: inline-block;"><pre style="letter-spacing: 0.544px;line-height: inherit;"><pre data-darkmode-bgcolor-15882384789136="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15882384789136="rgb(255, 255, 255)" data-style="letter-spacing: 0.544px; background-color: rgb(255, 255, 255); text-align: center; color: rgba(230, 230, 230, 0.9); font-size: 16px; line-height: 25.6px; overflow-wrap: break-word !important;" data-darkmode-bgcolor-15882396318564="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15882396318564="rgb(255, 255, 255)" data-darkmode-color-15882396318564="rgba(230, 230, 230, 0.9)" data-darkmode-original-color-15882396318564="rgba(230, 230, 230, 0.9)" data-darkmode-bgcolor-15900529136199="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15900529136199="rgb(255, 255, 255)" data-darkmode-color-15900529136199="rgba(230, 230, 230, 0.9)" data-darkmode-original-color-15900529136199="rgba(230, 230, 230, 0.9)" style="letter-spacing: 0.544px;text-align: center;color: rgba(230, 230, 230, 0.9);line-height: 25.6px;"><section><section data-darkmode-bgcolor-15860613985508="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15860613985508="rgb(255, 255, 255)" data-darkmode-color-15860613985508="rgb(230, 230, 230)" data-darkmode-original-color-15860613985508="rgb(0, 0, 0)" data-darkmode-bgcolor-15870356070738="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15870356070738="rgb(255, 255, 255)" data-darkmode-color-15870356070738="rgb(230, 230, 230)" data-darkmode-original-color-15870356070738="rgb(0, 0, 0)" data-darkmode-bgcolor-15870356071023="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15870356071023="rgb(255, 255, 255)" data-darkmode-color-15870356071023="rgb(230, 230, 230)" data-darkmode-original-color-15870356071023="rgb(0, 0, 0)" data-darkmode-bgcolor-15882384789136="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15882384789136="rgb(255, 255, 255)" data-darkmode-color-15882384789136="rgb(230, 230, 230)" data-darkmode-original-color-15882384789136="rgb(0, 0, 0)" data-darkmode-bgcolor-15882396318564="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15882396318564="rgb(255, 255, 255)" data-darkmode-color-15882396318564="rgb(230, 230, 230)" data-darkmode-original-color-15882396318564="rgb(0, 0, 0)" data-darkmode-bgcolor-15900529136199="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15900529136199="rgb(255, 255, 255)" data-darkmode-color-15900529136199="rgb(230, 230, 230)" data-darkmode-original-color-15900529136199="rgb(0, 0, 0)" style="display: inline-block;clear: both;"><section data-tools="135编辑器" data-id="91842" data-darkmode-bgcolor-15860613985508="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15860613985508="rgb(255, 255, 255)" data-darkmode-color-15860613985508="rgb(230, 230, 230)" data-darkmode-original-color-15860613985508="rgb(0, 0, 0)" data-darkmode-bgcolor-15870356070738="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15870356070738="rgb(255, 255, 255)" data-darkmode-color-15870356070738="rgb(230, 230, 230)" data-darkmode-original-color-15870356070738="rgb(0, 0, 0)" data-darkmode-bgcolor-15870356071023="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15870356071023="rgb(255, 255, 255)" data-darkmode-color-15870356071023="rgb(230, 230, 230)" data-darkmode-original-color-15870356071023="rgb(0, 0, 0)" data-darkmode-bgcolor-15882384789136="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15882384789136="rgb(255, 255, 255)" data-darkmode-color-15882384789136="rgb(230, 230, 230)" data-darkmode-original-color-15882384789136="rgb(0, 0, 0)" data-darkmode-bgcolor-15882396318564="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15882396318564="rgb(255, 255, 255)" data-darkmode-color-15882396318564="rgb(230, 230, 230)" data-darkmode-original-color-15882396318564="rgb(0, 0, 0)" data-darkmode-bgcolor-15900529136199="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15900529136199="rgb(255, 255, 255)" data-darkmode-color-15900529136199="rgb(230, 230, 230)" data-darkmode-original-color-15900529136199="rgb(0, 0, 0)" style="letter-spacing: 0.544px;border-width: 0px;border-style: none;border-color: initial;"><section data-darkmode-bgcolor-15860613985508="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15860613985508="rgb(255, 255, 255)" data-darkmode-color-15860613985508="rgb(230, 230, 230)" data-darkmode-original-color-15860613985508="rgb(0, 0, 0)" data-darkmode-bgcolor-15870356070738="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15870356070738="rgb(255, 255, 255)" data-darkmode-color-15870356070738="rgb(230, 230, 230)" data-darkmode-original-color-15870356070738="rgb(0, 0, 0)" data-darkmode-bgcolor-15870356071023="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15870356071023="rgb(255, 255, 255)" data-darkmode-color-15870356071023="rgb(230, 230, 230)" data-darkmode-original-color-15870356071023="rgb(0, 0, 0)" data-darkmode-bgcolor-15882384789136="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15882384789136="rgb(255, 255, 255)" data-darkmode-color-15882384789136="rgb(230, 230, 230)" data-darkmode-original-color-15882384789136="rgb(0, 0, 0)" data-darkmode-bgcolor-15882396318564="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15882396318564="rgb(255, 255, 255)" data-darkmode-color-15882396318564="rgb(230, 230, 230)" data-darkmode-original-color-15882396318564="rgb(0, 0, 0)" data-darkmode-bgcolor-15900529136199="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15900529136199="rgb(255, 255, 255)" data-darkmode-color-15900529136199="rgb(230, 230, 230)" data-darkmode-original-color-15900529136199="rgb(0, 0, 0)" style="display: inline-block;clear: both;"><section data-brushtype="text" data-darkmode-bgcolor-15860613985508="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15860613985508="rgb(255, 255, 255)" data-darkmode-color-15860613985508="rgb(230, 230, 230)" data-darkmode-original-color-15860613985508="rgb(0, 0, 0)" data-darkmode-bgimage-15860613985508="1" data-style="padding: 18px 15px 20px 10px; color: rgb(86, 146, 214); text-align: center; letter-spacing: 1.5px; background-image: url('https://www.zkxjob.com/wp-content/uploads/2022/06/wxsync-2022-06-a2a8a5e1e58f30392066a170034ee027.png'); background-size: 100% 100%; background-repeat: no-repeat; overflow-wrap: break-word !important;" data-darkmode-bgcolor-15870356070738="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15870356070738="rgb(255, 255, 255)" data-darkmode-color-15870356070738="rgb(230, 230, 230)" data-darkmode-original-color-15870356070738="rgb(0, 0, 0)" data-darkmode-bgimage-15870356070738="1" data-darkmode-bgcolor-15870356071023="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15870356071023="rgb(255, 255, 255)" data-darkmode-color-15870356071023="rgb(230, 230, 230)" data-darkmode-original-color-15870356071023="rgb(0, 0, 0)" data-darkmode-bgimage-15870356071023="1" data-darkmode-bgcolor-15882384789136="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15882384789136="rgb(255, 255, 255)" data-darkmode-color-15882384789136="rgb(230, 230, 230)" data-darkmode-original-color-15882384789136="rgb(0, 0, 0)" data-darkmode-bgimage-15882384789136="1" data-darkmode-bgcolor-15882396318564="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15882396318564="rgb(255, 255, 255)" data-darkmode-color-15882396318564="rgb(230, 230, 230)" data-darkmode-original-color-15882396318564="rgb(0, 0, 0)" data-darkmode-bgimage-15882396318564="1" data-darkmode-bgcolor-15900529136199="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15900529136199="rgb(255, 255, 255)" data-darkmode-color-15900529136199="rgb(230, 230, 230)" data-darkmode-original-color-15900529136199="rgb(0, 0, 0)" data-darkmode-bgimage-15900529136199="1" style="padding: 18px 15px 20px 10px;background-size: 100% 100%;background-image: url('https://www.zkxjob.com/wp-content/uploads/2022/06/wxsync-2022-06-a2a8a5e1e58f30392066a170034ee027.png');color: rgb(86, 146, 214);letter-spacing: 1.5px;background-repeat: no-repeat;"><section data-darkmode-bgcolor-15860613985508="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15860613985508="rgb(255, 255, 255)" data-darkmode-color-15860613985508="rgb(230, 230, 230)" data-darkmode-original-color-15860613985508="rgb(0, 0, 0)" data-darkmode-bgimage-15860613985508="1" data-darkmode-bgcolor-15870356070738="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15870356070738="rgb(255, 255, 255)" data-darkmode-color-15870356070738="rgb(230, 230, 230)" data-darkmode-original-color-15870356070738="rgb(0, 0, 0)" data-darkmode-bgimage-15870356070738="1" data-darkmode-bgcolor-15870356071023="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15870356071023="rgb(255, 255, 255)" data-darkmode-color-15870356071023="rgb(230, 230, 230)" data-darkmode-original-color-15870356071023="rgb(0, 0, 0)" data-darkmode-bgimage-15870356071023="1" data-darkmode-bgcolor-15882384789136="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15882384789136="rgb(255, 255, 255)" data-darkmode-color-15882384789136="rgb(230, 230, 230)" data-darkmode-original-color-15882384789136="rgb(0, 0, 0)" data-darkmode-bgimage-15882384789136="1" data-darkmode-bgcolor-15882396318564="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15882396318564="rgb(255, 255, 255)" data-darkmode-color-15882396318564="rgb(230, 230, 230)" data-darkmode-original-color-15882396318564="rgb(0, 0, 0)" data-darkmode-bgimage-15882396318564="1" data-darkmode-bgcolor-15900529136199="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15900529136199="rgb(255, 255, 255)" data-darkmode-color-15900529136199="rgb(230, 230, 230)" data-darkmode-original-color-15900529136199="rgb(0, 0, 0)" data-darkmode-bgimage-15900529136199="1" style="display: flex;justify-content: center;align-items: center;"><section data-darkmode-bgcolor-15860613985508="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15860613985508="rgb(255, 255, 255)" data-darkmode-color-15860613985508="rgb(230, 230, 230)" data-darkmode-original-color-15860613985508="rgb(0, 0, 0)" data-darkmode-bgimage-15860613985508="1" data-darkmode-bgcolor-15870356070738="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15870356070738="rgb(255, 255, 255)" data-darkmode-color-15870356070738="rgb(230, 230, 230)" data-darkmode-original-color-15870356070738="rgb(0, 0, 0)" data-darkmode-bgimage-15870356070738="1" data-darkmode-bgcolor-15870356071023="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15870356071023="rgb(255, 255, 255)" data-darkmode-color-15870356071023="rgb(230, 230, 230)" data-darkmode-original-color-15870356071023="rgb(0, 0, 0)" data-darkmode-bgimage-15870356071023="1" data-darkmode-bgcolor-15882384789136="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15882384789136="rgb(255, 255, 255)" data-darkmode-color-15882384789136="rgb(230, 230, 230)" data-darkmode-original-color-15882384789136="rgb(0, 0, 0)" data-darkmode-bgimage-15882384789136="1" data-darkmode-bgcolor-15882396318564="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15882396318564="rgb(255, 255, 255)" data-darkmode-color-15882396318564="rgb(230, 230, 230)" data-darkmode-original-color-15882396318564="rgb(0, 0, 0)" data-darkmode-bgimage-15882396318564="1" data-darkmode-bgcolor-15900529136199="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15900529136199="rgb(255, 255, 255)" data-darkmode-color-15900529136199="rgb(230, 230, 230)" data-darkmode-original-color-15900529136199="rgb(0, 0, 0)" data-darkmode-bgimage-15900529136199="1" style="margin-left: 2px;width: 20px;"></section><section data-brushtype="text" data-darkmode-bgcolor-15860613985508="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15860613985508="rgb(255, 255, 255)" data-darkmode-color-15860613985508="rgb(51, 51, 51)" data-darkmode-original-color-15860613985508="rgb(51, 51, 51)" data-darkmode-bgimage-15860613985508="1" data-darkmode-bgcolor-15870356070738="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15870356070738="rgb(255, 255, 255)" data-darkmode-color-15870356070738="rgb(51, 51, 51)" data-darkmode-original-color-15870356070738="rgb(51, 51, 51)" data-darkmode-bgimage-15870356070738="1" data-darkmode-bgcolor-15870356071023="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15870356071023="rgb(255, 255, 255)" data-darkmode-color-15870356071023="rgb(51, 51, 51)" data-darkmode-original-color-15870356071023="rgb(51, 51, 51)" data-darkmode-bgimage-15870356071023="1" data-darkmode-bgcolor-15882384789136="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15882384789136="rgb(255, 255, 255)" data-darkmode-color-15882384789136="rgb(51, 51, 51)" data-darkmode-original-color-15882384789136="rgb(51, 51, 51)" data-darkmode-bgimage-15882384789136="1" data-darkmode-bgcolor-15882396318564="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15882396318564="rgb(255, 255, 255)" data-darkmode-color-15882396318564="rgb(51, 51, 51)" data-darkmode-original-color-15882396318564="rgb(51, 51, 51)" data-darkmode-bgimage-15882396318564="1" data-darkmode-bgcolor-15900529136199="rgb(36, 36, 36)" data-darkmode-original-bgcolor-15900529136199="rgb(255, 255, 255)" data-darkmode-color-15900529136199="rgb(51, 51, 51)" data-darkmode-original-color-15900529136199="rgb(51, 51, 51)" data-darkmode-bgimage-15900529136199="1" style="font-size: 14px;color: rgb(51, 51, 51);text-align: left;"><span style="font-family: 楷体, 楷体_GB2312, SimKai;">点这里,获取一大波福利</span></section></section></section></section></section></section></section>
本篇文章来源于: 菜鸟学Python
本文为原创文章,版权归知行编程网所有,欢迎分享本文,转载请保留出处!
你可能也喜欢
- ♥ 小白必看的python中的bool运算和真假值10/28
- ♥ 如何在python3中取幂11/13
- ♥ 如何在python中编写代码09/29
- ♥ 如何才能学好Python|花钱都买不到的秘诀03/02
- ♥ Python的交互方式与直接运行.py文件的区别详解10/07
- ♥ Python 和 Shell 脚本之间的交互11/24
内容反馈