说服别人评论他们的代码有什么好的理由？
我注意到许多程序员喜欢编写代码的速度,而没有评论而是为自己和其他人留下一些文档.当我试图说服他们时,我会听到一半被烘焙的东西,比如"方法/班级名称应该说它做什么"等等.你会怎么说他们改变主意？
如果您反对评论,请发表评论.对于试图说服人们评论代码的人来说,这应该是一种资源,而不是其他.:-)
其他相关问题是:评论代码,您是否评论您的代码以及您希望如何评论.
只评论"为什么"而不是"什么".到目前为止,我同意,从类或方法或变量名称应该清楚它的作用和用途.重构而不是评论它.
如果你采用这种方法,你会得到评论,你会得到有用的评论.程序员喜欢解释他们为什么要做某事.
从6个月前向他们展示自己的代码.如果他们无法理解并在2到4分钟内准确概述它的作用,那么你的观点可能就已经完成了.
我的看法:
我不会.方法/类名应该说明它的作用.如果没有,那么方法或类都试图做得太多,或者它的命名很差.
我很喜欢评论为什么,而不是什么.如果不清楚为什么代码使用一种方法而不是另一种方法,请对其进行评论.如果你不得不添加一个黑客未使用的变量来解决编译器错误,请注释原因.但是像"//连接数据库"这样的评论是代码错误或政策不好的迹象.名为ConnectToDatabase()的方法要好得多.如果它中有"//确定数据库服务器IP",那么可能应将其拉出到名为"DetermineDbServerIPAddress()"的方法中.
设计可以记录在案,但评论通常是该级别文档的不利位置.凭借对设计的了解,以及对原因的一些评论,应该是什么以及如何应该是显而易见的.如果不是,而不是说服他们评论他们的代码,让他们改进它.
也许这只是必须从经验中学到的东西; 特别是,六个月后回到你自己的代码的经验,并试图找出你在写它时你在想什么(或你在做什么).这当然使我确信评论不是一个坏主意.
给他们一些(约500行,最少)可怕的,未注释的意大利面条代码来重构.确保变量没有逻辑命名.空白可选.
看看他们喜欢它!
过于苛刻,但一次性得到两分.
写好你的代码.
评论它,以便您和其他人知道这意味着什么.
我应该强调,这段代码不应该源于它们.评论是为了解自己的代码,月下来真的很有用,但他们也近了,就必需理解的复杂零件别人的代码.他们需要了解其他人可能必须了解他们正在做的事情.
最后一次编辑:评论质量也非常重要.一些开发人员在他们的工作中具有几乎2:1的代码与注释比率,但这并不能使他们成为好评.您的代码中的注释可能会少得多,但仍然有很多意义.
解释你在做什么.您的代码质量应该为您完成大部分工作.
更重要的是,解释你为什么要做某事!我已经看到了很多代码,这些代码确切地说明了某些事情正在做什么并且没有真正的想法为什么开发人员(不幸的是我在大多数时候)认为这首先是一个好主意.
提醒他们阅读代码只能告诉他们代码的作用,而不是它应该做什么.
如果您或其他开发人员尚未阅读代码完成(或代码完成2),那么请停止正在执行的操作并阅读它.
有一点值得一提的是"一个功能应该只做一件事并且做得好".当这样一个函数以一件事命名时,它还能做什么进一步需要评论？
评论的习惯是与他们应该描述的代码不同步.结果可能比没有原始评论更糟糕.不仅如此,开发人员知道评论可能会老化而且不可信任.因此,他们会阅读代码并自己辨别它实际上在做什么!这样就无法将评论放在首位.
虽然已经说过一个函数名称也是如此,但它可能已经完全命名,但是已经添加了超时的新操作,这些操作在名称中没有提到.
所有注释似乎都将开发人员希望更接近的代码行分开,以便他们可以在每个屏幕上看到更多.我知道自己对一段代码的重新操作有很多我必须理解的评论.删除所有评论.现在我可以看到代码是什么了.
在一天结束的时候,如果你花时间把事情做好,你的时间会更好地重构代码,以确保它可以合理地自我描述,而不仅仅是写评论.这样的练习以其他方式得到回报,例如识别常见的代码块.
值得注意的是,许多优秀的开发人员更喜欢编写清晰的C#,Java,而不是那些精确度低得多的人类语言,他们拥有所有的假设和含糊之处.大多数具有常识的人都会知道细节有多少是足够的细节,但优秀的开发人员不是"大多数人".这就是为什么我们最终得到的评论\\adds a to b and store it in c(好吧,这太极端,但你明白了).
要求他们做一些他们讨厌做的事情并且坦率地说并不擅长(即使你确信这是正确的事情)只是一场已经失败的战斗.
我会说"昨天我必须阅读你的一些代码.我能够理解它,但是不到或等于5条精心挑选的评论解释如何完成它的目标将允许我阅读它的大约一个 - 至少时间,然后我可能会担心理解问题.我不是傻瓜,你不聪明,因为你可以写出难以理解的东西.相反,如果你不能产生可读的文档+代码集合,那么你不是一个开发人员."
我很久以前就把这个钻进了我的脑海里:如果你写了一些东西而且有合理能力的人无法理解,那就是你的错,而不是他或她的错.这适用于用自然语言书写,它适用于用编程语言编写.
我不是在嘲笑你,但你应该重新思考这个问题.你如何说服其他开发者团队合作？
说真的,有些人认为你可以读懂他们的想法.
如果您是敏捷团队的一员,则代码是集体所有,因此当您看到未注释,笨拙或难以阅读的代码时,请继续并更改(重构)它以便您理解它.如果有人抱怨,请告诉他们为什么并提前做好准备.你发现它不可理解,没有人拥有代码.
我们的策略是进行系统的代码审查,并拒绝未正确记录的代码(通过评论,正确的功能命名和组织等).如果评论者不清楚,你会回到工作台上.
关于评论也有过类似的讨论.以下是评论代码时人们遵循的规则:关于评论代码的"硬规则"是什么？.一些答案也有很好的理由说明为什么要对代码进行注释.
京公网安备 11010802040832号 | 京ICP备19059560号-6 