Leo*_*eda 11 formatting comments use-case
我总是讨厌用星号填充屏幕一半的评论只是为了告诉你函数返回一个字符串,我从来没有读过这些评论.
但是,我确实阅读了一些评论,这些评论描述了为什么要完成某些事情以及它是如何完成的(通常是代码中的单行注释); 那些在试图理解别人的代码时非常方便.
但是当谈到写评论时,我不写那个,相反,我只是在编程竞赛中编写算法时使用注释,我会想到算法将如何做它然后我会写一个注释,然后编写与该注释对应的代码.
一个例子是:
//loop though all the names from n to j - 1
除此之外,我无法想象为什么有人会在写代码时浪费宝贵的时间撰写评论.
我是对还是错？我错过了什么吗？还有哪些其他好用的评论用例我不知道？
Jar*_*Par 17
评论应该表达为什么你做的不是你正在做的事情
这是一句古老的格言,但使用的一个好指标是:
评论为什么你正在做的事情,而不是如何你这样做.
说"从n到j-1遍历所有名称"应该立即清楚,即使是新手程序员也只能从代码中解决.给出你这样做的原因有助于提高可读性.
如果你使用像Doxygen这样的东西,你可以完全记录你的返回类型,参数等,并生成一个很好的"源代码手册".我经常为客户端执行此操作,以便继承我的代码的团队不会完全丢失(或强制审查每个标头).
文档块通常过度,特别是强类型语言.使用Python或PHP之类的东西比使用C++或Java更加冗长.也就是说,对于不自我解释的方法和成员(例如,未命名更新),它仍然很好.
如果我第一次阅读我的代码,只需通过评论我想要告诉自己的内容,我就可以节省很多时间.更多的叙述和更少的观察.评论不仅应该帮助别人,还应该帮助自己 ......特别是如果你在五年内没有提到它.我写了一些十岁的Perl,我仍然不知道它的作用.
我用PHP和Python完成的非常脏的东西是使用反射来检索用户界面中的注释块和标签元素.这是一个用例,虽然令人讨厌.
如果使用错误跟踪器,我还会在我的更改附近删除错误ID,以便我有一个返回跟踪器的引用.这是对更改的简要描述(内联更改日志)的补充.
当我做一些我的同事很少看到的东西时......或者当微妙的重要性时,我也违反了"唯一的评论为什么不是什么"的规则.例如:
for (int i = 50; i--; ) cout << i; // looping from 49..0 in reverse
for (int i = 50; --i; ) cout << i; // looping from 49..1 in reverse