当前位置:学习生活->资讯娱乐 ->年度最可爱最认真最负责最个性化的代码注释为这般

原创版权标志年度最可爱最认真最负责最个性化的代码注释为这般

作者:codexia  发表时间:2016/8/12 15:27:51  阅读:
[摘要] 截取了一份代码头文件的几处注释,完全阐释了注释的价值和魅力所在,透露出来作者认真负责,可爱个性的一面,不禁让人喜爱上了作者。文中列出了9个特点的注释,每一个注释都做了一个简单的解释,大家都来学习一下吧。

    接手了一个项目,阅读项目源码时,发现注释真个性化,非常可爱,不忍心不分享出来。就拿其中一个文件的注释分享吧,估计整个项目到处都有这样个性化可爱的注释。感觉代码作者在跟阅读代码的人交流一样,感觉非常不错。

1.文件开头的声明


/*!
@copyright 2004-2013 Apache License, Version 2.0 FULLSAIL
@filename zen_predefine.h
@author xxx <xxx@gmail.com>
@version
@date 2003-5-14
@brief 所有预定义信息描述,包括所有的外部头文件,全局使用的宏,
 个个平台兼容性的一些小东东,数值的typedef,

 @details 在yunfei改进后的再改进一下,发现每个人看问题的思路还是不一样的。
 也吸取教训,写注释,免得大家不理解为啥要这样
 请大家仔细看一下每段的分割线和说明,我认为我的划分是很清晰的,不要
 一看就认为代码宏定义混乱,
 请各位大神动之前放慢你奔腾野马式样的思维,仔细阅读一下注释
 头文件分成几个个部分,操作系统定义,头文件包含,数值定义,一些常用宏,

 头文件包含情况如下
 1.WINDOWS特有部分的,主要是WINDOWS兼容东西多,容易冲突,甚至Windows
 那排文件的定义顺序也是有讲究的
 2.LINUX特有部分的,
 3.C头文件
 4.C++特有部分的,
 5.依赖的第3方的库的,请务必不要搞乱,(大部分都是可以打开关闭的)

 数值定义typedef部分代码,以及相关的头文件信息,
 宏的定义以宏为核心,不按照操作系统分开,免得找起来痛苦,不要试图归类,
 而改变顺序,反而让人难以理解,

 记录一点纯属YY,的东东,
 一个得道修仙老前辈送的一段话,记录下来:
 侠者,性情也,意气也。故不文,不饰,不求,不争,合则留,不合则去。故卫青,
 将也;周亚夫,侠也;徐达,将也;常遇春,侠也。真侠近乎道。
 我回复:
 神,请赐予我平静, 去接受我无法改变的。
 给予我勇气,去改变我能改变的,
 赐我智慧,分辨这两者的区别。
*/
     注释交代了一个朋友的改进,发表了自己的感想。然后怕自己的代码因为别人粗心大意没看懂,就喷自己,所以做了一些说明,以免被误解了。最后还来一段YY的东西,太有才了。我想起了原来我自编了一首诗,改自《面向大海,春暖花开》,表达了我这个程序员喜欢编程,渴望成为一个优秀的架构师的梦想。被原来的同事写在了注释里,和这里差不多。哈哈哈。原文没有记录在网站里,就懒得找了。


2.全局的注释


//根据操作系统,编译器,给出不同的定义,因为这些定义会影响全局,所以在最开始的部分
//我的库只打算适应两个环境,Windows(MSVC)和Linux(GCC),
     因为这个项目是跨平台的,所以会根据操作系统的不同而定义不同的系统的东西。重点是,“我的库”,让人感觉这个库不是冷冰冰的,而是我在维护的。感觉比较好。


3.全局注释的局部细节的补充


// LINUX平台(GCC)我只打算支持GCC,不好意思
     因为只支持GCC,不支持其他编译器,免得小伙伴们在用其他编译器时有问题而烦躁,这里特别注明了。还表达了万分的歉意和傲慢的决定。有个性!!


4.对自己的自信的可爱注释


//如果你啥都不是或者啥都是,我不活了。
#if (!defined (ZEN_OS_WINDOWS) && !defined (ZEN_OS_LINUX)) || (defined (ZEN_OS_WINDOWS) && defined (ZEN_OS_LINUX))
#error " ZEN_OS_WINDOWS and ZEN_OS_LINUX all defined or all undefined. error."
#endif //
     要么就是太自信,要么就是很直率,反正就这样了,要杀要剐,悉听尊便!很有意思。


5.对编译器GCC版本的描述


//LINUX GCC下的告警屏蔽功能,其必须在GCC 4.2以后才有,而且push,pop的功能,必须在GCC,4.6以后才有,
//这两个屏蔽告警的东东要等待GCC4.6以后才有。命苦的人。
//#pragma GCC diagnostic push
//#pragma GCC diagnostic pop
     这可以让使用此项目的程序员迅速避开GCC版本带来的困扰,而且只能表达人生坎坷,造物弄人呀!哈哈哈。“命苦的人”是多么无奈呀。我都长发及腰了,你还没有出生。


6.前缀使用注释


// 在WINDOWS下和POSIX标准兼容的宏,VS2003以下版本如何,我没有测试,2003以后,Windows对于很多代码宏会使用"_"前缀,
#define _CRT_NONSTDC_NO_DEPRECATE 1
#define _CRT_NONSTDC_NO_WARNINGS 1
     明确表明自己对VS2003版本一下没有测试,可以让读者知道,VS2003以下版本发生重大事故,不要怪我咯。而且,我测试的,都不会有问题的哦。而且,会用"_"前缀哦。看得出作者很用心。


7.善意的提醒注释


// 重新定义FD_SETSIZE来,要在winsock2.h前面,也请其他人注意
//有些文件前缀是大写的,看起来怪怪的,但Windows下他就真是大写的。
//在VS2008以后,才有hash_map和hash_set,所以在这之前,你必须用stlport,
//当然由于stlport的性能强过微软自带的容器,其他版本也建议大家用stlport
     第一个说的是宏定义时与其他头文件的关系,如果前后顺序弄错,会出现错误,所以这个注释很有意义,很多人会忽略这样的注释,以为自己知道了就不用加注释了。然而时间久了,可能自己也搞不清楚了,看的人也不知道还有顺序需要注意。而Windows的一些头文件的名称,也做了自己的看法,“怪是怪了点,但是人家真是这样哦。”,哈哈哈哈。


    后面两个可以看出作者知识面很广,对于VS版本的差异还是很清楚的,并且给了使用建议。赞一个。

8.知识性注释,背景介绍


//考虑字节序的读取短整型,整形,64位长整形的方式
//不好意思,年纪大了,记忆力真的有点成问题了,有几次写这段东东就是想不明白加密,MD5等代码中为啥要考
//虑字节序处理呢?
//第一,为了保持算法的一致性,一台小头字节序机器上计算的得到的密文,在另外一台大头序的机器要能解开,
//(或者说大头和小头的机器对同样的一段buffer,加密得到的密文应该是一致的)
//这就要求计算机从字节流中取出的整数含义是一致的。所以就要求考虑字节序问题了。这是最关键的因素。
//第二,有些算法是为了加快处理,表面是用整数处理的,但实际里面,是必须考虑字节顺序的,比如我们的
//CRC32算法,就有这个问题,所以这种算法,你必须考虑字节序问题,小头在这种情况下往往不需要进行转,
//第三,有些算法其实明确要求了里面采用大头序,还是小头序,这种你就必须考虑你的环境,
//
//在默认编码的问题上,我还是倾向了小头,一方面我的代码估计99.99%都是跑在X86架构之下,另一方面
//小头的是从低到高,和字节顺序一致,处理上也方便一点。
     这样的注释,你可以学到很多东西。而且维护的人可以通过这样的注释学到知识的同时,还提高了维护的效率。作者自己在改善代码时也是可以避免绕回来。写清楚了,好处多多呀。


9.纯粹的科普知识注释


//路径的最大长度,
//普及一下小知识,注意一下其实MAX_PATH未必真正够用,MS一般的定义是260,但是,其实你可以超过,
     作者已经不只是在写代码了,完全将这里当做自己思想交流表达的地方,程序员的世界,是多么精彩的,请细细感受这些代码,可以很好的理解作者,因为这里就是他内心深处的某一个美好的角落。



    一个头文件给我们展示了这么多的注释形式,让我受益匪浅。先不说注释本身带来的学习价值,就这样的编程态度和认真负责的态度,让人佩服的五体投地。用心用情,用得淋漓尽致,这才是这些代码的魅力所在。所以,这样的注释风格,是我们非常值得学习的地方。

    最后问一句,这个代码作者可爱吗?大家顶起来,说不定作者会看到哦。

文章来源:C++技术网原创文章版权为网站和作者共同所有,会员文章禁止转载。非会员文章转载做好本文超链接即表示授权转载。通过文章下面的分享按钮可以自由分享所有文章。


  • dx    2016/8/12 16:15:10回复
    向代码作者学习~

  • raychang988    2016/8/12 16:14:20回复
    沙发

  • raychang988    2016/8/12 16:23:16回复
    我猜肯定会有项目经理觉得这注释写的太多了dx: 回复 raychang988 说:项目经理不会在意这个,因为他们根本不懂代码,哈哈哈【回复】

返回顶部

在线提问
问题标题:
问题描述:(简陋的描述会导致问题被最后回答、没有针对性回答甚至无法解答。请确保问题描述的足够清楚。)