如何在不“需要”的情况下编写代码？评论的可读性？
可能的重复：
是否可以写得既好又容易理解代码没有任何注释？
经常编码时，我听说如果需要注释，则意味着代码太难理解。我同意代码应该是可读的，但由于“管道”和奇怪的语法，语言本身常常使代码难以理解。我最常使用的语言是：
Java 穆工具 红宝石 Erlang
有什么建议吗？ 谢谢
Possible Duplicate:
Is it possible to write good and understandable code without any comments?
When coding often I hear that if comments are needed then it means that the code is too hard to understand. I agree that code should be readable but often the language itself makes the code hard to follow, because of "plumbing" and strange syntax. The languages I use most often are:
Java
Mootools
Ruby
Erlang
Any tips would be appreciated?
Thanks
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（7）
推荐阅读：Robert C. Martin 的整洁代码。
简而言之，您应该
不要害怕从
if语句中提取哪怕是中等复杂的表达式；哪个更容易阅读，这个或
（不要试图在第一个代码片段中找到任何含义，我只是编造的:-)
几乎不需要干净代码中的注释。我能想到的唯一例外是，如果您使用一些晦涩的语言功能（例如 C++ 模板元编程）或算法，并且您在注释中给出了方法/算法的来源及其实现细节的引用。
从长远来看，任何其他类型的注释都不是很有用，主要原因是代码会发生变化，而注释往往不会随着相应代码的更改而更新。因此，过了一段时间，该注释不仅毫无用处，而且具有误导性：它告诉您一些内容（实现说明、设计选择的推理、错误修复等），这些内容涉及早已消失的代码版本，并且您已经不知道它是否与当前版本的代码相关。
我认为“为什么我选择这个解决方案”通常不值得在代码中记录的另一个原因是，此类评论的简短版本几乎总是像“因为我认为这是最好的方法”，或者参考“C++ 编程语言，第 5.2.1 章”，长版本将是一篇三页的文章。我认为经验丰富的程序员最常看到并理解为什么代码是这样写的，而无需太多解释，而初学者可能甚至连解释本身都不理解 - 不值得尝试覆盖所有人。
最后但并非最不重要的一点是，IMO 单元测试几乎总是比代码注释更好的文档方式：单元测试确实非常有效地记录了您对代码的理解、假设和推理，此外，系统会自动提醒您使它们与代码保持同步每当你破坏它们时（好吧，只要你在构建中实际运行它们......）。
Recommended reading: Clean Code by Robert C. Martin.
In brief, you should
Don't fear of extracting even moderately complex expressions from
ifstatements; which one is clearer to read, thisor
(Don't try to find any meaning in the first code snippet, I just made it up :-)
Comments in clean code are almost never needed. The only exceptions I can think of is if you are using some obscure language feature (e.g. C++ template metaprogramming) or algorithm, and you give a reference to the source of the method/algorithm and its implementation details in a comment.
The main reason why any other kind of comments is not very useful in the long run is that code changes, and comments tend to not be updated alongside the changes in the corresponding code. So after a while the comment is not simply useless, but it is misleading: it tells you something (implementation notes, reasoning about design choices, bug fixes etc.) which refers to a version of the code which is long gone, and you have no idea whether it is relevant anymore for the current version of the code.
Another reason why I think that "why I chose this solution" is most often not worth documenting in the code, is that the brief version of such a comment would almost always be like either "because I think this is the best way", or a reference to e.g. "The C++ Programming Language, ch. 5.2.1", and the long version would be a three-page essay. I think that an experienced programmer most often sees and understands why the code is written like this without much explanation, and a beginner may not understand even the explanation itself - it's not worth trying to cover everyone.
Last but not least, IMO unit tests are almost always a better way of documentation than code comments: your unit tests do document your understanding, assumptions and reasoning about the code quite efficiently, moreover you are automatically reminded to keep them in sync with the code whenever you break them (well, provided you actually run them with your build...).
我认为你通常无法在没有注释的情况下编写代码。
简而言之，代码记录了如何。评论记录了原因。
我希望注释能够指出这样编写代码的条件、需求或外部性所施加的限制、更改代码所产生的影响以及其他问题。注释包含代码本身未包含的信息。
I don't think you can normally write code without comments.
Briefly, the code documents how. The comments document why.
I would expect the comments to indicate the conditions why the code has been written like that, limitations imposed by requirements or externalities, the impact that would result from changing the code, and other gotchas. The comments contain information that isn't contained within the code itself.
代码中的注释应该告诉您为什么最初以某种方式执行某些操作。这并不意味着代码太难理解。
Comments along the code are supposed to tell you why you initially did something a certain way. It shouldn't mean the code is too hard to understand.
要遵循的最重要的事情是：
The most important things to follow are:
我认为为代码的用户编写注释很有用 - 类/方法/函数的作用、何时调用它等。换句话说，记录 API。
如果您需要评论一个方法如何为维护者的利益工作，那么我认为代码可能太复杂了。在这种情况下，正如其他人所说，将其重构为更简单的函数。
I think it is useful to write comments for USERS of your code - what the classes/methods/functions do, when an how to call it etc. In other words document the API.
If you need to comment how a method works for the benefit of maintainers then I think the code is probably too complex. In that case refactor it into simpler functions, as others have said.
我个人认为，完全没有评论和过度评论一样糟糕。您只需要找到合适的平衡点即可。关于对这件事使用长描述性名称对我来说总结如下： 阅读此内容 另请阅读 Kernighan &派克长名字。
I personally feel that having no comments at all is about as bad as having excessive commenting. You just need to find the right balance. About using long descriptive names for things this about sums it up for me: read this Also read Kernighan & Pike on long names.
您需要遵循某些规则。
Factory，则将其命名为FooFactory。You need to follow certain rules.
Factoryname itFooFactory.