JM:I have a dream,期待和你一起去实现!
原文及译文
JM
网友:Adam Davis

        我有一个同事坚持认为他的代码不需要评论,这是“自我记录”。我已经回顾了他的代码,虽然它比我见过其他代码更清晰,但我仍然不同意自我记录代码是完整有用的...

推荐:想去Google查资料?(你懂的)想建站?想测试?想挂机?想折腾?想要高性价比的服务器?点我!!


什么是自我记录代码,它可以代替有据可查的代码? [关闭](What is self-documenting code and can it replace well documented code? [closed])

我有一个同事坚持认为他的代码不需要评论,这是“自我记录”。

我已经回顾了他的代码,虽然它比我见过其他代码更清晰,但我仍然不同意自编档代码是完整且有用的,以及注释和文档代码。

帮助我理解他的观点。

What is self documenting code Can it really replace well commented and documented code Are there situations where it's better than well documented and commented code Are there examples where code cannot possibly be self-documenting without comments

也许这只是我自己的限制,但我不认为这是一个好的做法。

这不是一个争论 - 请不要提出为什么评论和文档编码是高优先级的原因 - 有很多资源显示这一点,但他们不相信我的同行。我相信我需要更充分地理解他的观点,否则就说服他。如果你必须开始一个新的问题,但不要在这里争论。

哇,快回复!请阅读所有现有的答案,并提供意见的答案,而不是添加新的答案,除非你的答案真的是大大不同于这里的其他答案。

而且,那些反对自我记录代码的人 - 主要是帮助我理解自我记录代码传播者的观点(即积极方面)。我希望如果你不停留在话题上,其他人会低估你。


I have a colleague who insists that his code doesn't need comments, it's "self documenting."

I've reviewed his code, and while it's clearer than code which I've seen others produce, I still disagree that self-documenting code is as complete and useful as well commented and documented code.

Help me understand his point of view.

What is self documenting code Can it really replace well commented and documented code Are there situations where it's better than well documented and commented code Are there examples where code cannot possibly be self-documenting without comments

Maybe it's just my own limitations, but I don't see how it can be a good practice.

This is not meant to be an argument - please don't bring up reasons why well commented and documented code is high priority - there are many resources showing this, but they aren't convincing to my peer. I believe I need to more fully understand his perspective to convince him otherwise. Start a new question if you must, but don't argue here.

Wow, quick response! Please read all the existing answers and provide comments to answers rather than add new answers, unless your answer really is substantially different from every other answer in here.

Also, those of you who are arguing against self documenting code -this is primarily to help me understand the perspective (ie, positive aspects) of self-documenting code evangelists. I expect others will downvote you if you don't stay on topic.


解决方案(由网友 OregonGhost 提供)

在我看来,任何代码都应该是自我记录的。在良好的,自我记录的代码中,你不必解释每一行,因为每个标识符(变量,方法,类)都有明确的语义名称。有更多的意见比必要的实际上更难(!)阅读代码,所以如果你的同事

writes documentation comments (Doxygen, JavaDoc, XML comments etc.) for every class, member, type and method AND clearly comments any parts of the code that are not self-documenting AND writes a comment for each block of code that explains the intent, or what the code does on a higher abstraction level (i.e. find all files larger than 10 MB instead of loop through all files in a directory, test if file size is larger than 10 MB, yield return if true)

他的代码和文档很好,在我看来。请注意,自行编写的代码并不意味着不应该有任何评论,但只应该没有不必要的评论。但是,通过阅读代码(包括注释和文档注释)应该立即理解代码的作用和原因。如果“自我记录”代码比注释代码花费更长时间才能理解,那么它并不是真正的自我记录。


In my opinion, any code should be self-documenting. In good, self-documented code, you don't have to explain every single line because every identifier (variable, method, class) has a clear semantic name. Having more comments than necessary actually makes it harder (!) to read the code, so if your colleague

writes documentation comments (Doxygen, JavaDoc, XML comments etc.) for every class, member, type and method AND clearly comments any parts of the code that are not self-documenting AND writes a comment for each block of code that explains the intent, or what the code does on a higher abstraction level (i.e. find all files larger than 10 MB instead of loop through all files in a directory, test if file size is larger than 10 MB, yield return if true)

his code and documentation is fine, in my opinion. Note that self-documented code does not mean that there should be no comments, but only that there should be no unnecessary comments. The thing is, however, that by reading the code (including comments and documentation comments) should yield an immediate understanding of what the code does and why. If the "self-documenting" code takes longer to understand than commented code, it is not really self-documenting.


推荐:想去Google查资料?(你懂的)想建站?想测试?想挂机?想折腾?想要高性价比的服务器?点我!!


关于站长

JMJavaMethod的缩写,苦逼码农一个,一直想有番作为,奈何人老力衰,只能四处膜拜大佬以获得动力。已经从单机、局域网、互联网、混到了移动互联网,未来希望能在AI世界里继续混下去。这辈子有个终极目标:财务自由,心灵自由。

近期公告

一个人苦逼开发多日,网站终于正式上线,求关注!!! 一个人苦逼多日,终于正式上线,求关注!!!

找他  
猜你喜欢
想建站?想测试?
想挂机?想折腾?
想去Google查资料?(你懂的)
想要高性价比的服务器?
搬瓦工VPS - 性价最高的美国便宜VPS主机
友情链接

冀ICP备17016304号 版权所有 © JavaMethod.com All Rights Reserved,Theme by 拼图