如何在没有"需要"注释的情况下编写代码以提高可读性？

Question

可能重复:
是否可以在没有任何注释的情况下编写好的和可理解的代码？

经常编码时,我听说如果需要注释,那就意味着代码太难理解了.我同意代码应该是可读的,但由于"管道"和奇怪的语法,语言本身通常会使代码难以遵循.我经常使用的语言是:

Java Mootools Ruby Erlang

任何提示将不胜感激？谢谢

Answer 1

推荐阅读:Robert C. Martin的清洁代码.

简而言之,你应该

• 使用有意义的变量/方法/类名,
• 保持你的功能/方法简短,
• 每个班级和方法只做一件事,
• 使每个方法中的代码处于相同的抽象级别.

不要害怕从if陈述中提取中等复杂的表达; 这个更清楚

if (i >= 0 && (v.size() < u || d == e)) ...

要么

if (foundNewLocalMaximum()) ...

(不要试图在第一个代码片段中找到任何含义,我只是编写了:-)

几乎不需要干净代码中的注释.我能想到的唯一例外是,如果您使用的是一些模糊的语言功能(例如C++模板元编程)或算法,并且您在注释中提供了方法/算法的来源及其实现细节的参考.

从长远来看,任何其他类型的注释都不是很有用的主要原因是代码更改,并且注释往往不会随着相应代码中的更改而更新.所以过了一段时间,评论不是简单无用,而是误导性的:它告诉你一些事情(实现说明,关于设计选择的推理,错误修复等),这些指的是一个很久以前的代码版本,你有不知道它是否与当前版本的代码相关.

我认为"为什么我选择这个解决方案"的另一个原因通常是不值得在代码中记录,这个评论的简短版本几乎总是像"因为我认为这是最好的方式",或者参考例如"The C++ Programming Language,ch.5.2.1",长版本将是一篇三页的文章.我认为有经验的程序员经常看到并理解为什么代码是这样写的而没有太多的解释,初学者甚至可能无法理解解释本身 - 不值得尝试覆盖每个人.

最后但同样重要的是,IMO单元测试几乎总是比代码注释更好的文档管理方式:您的单元测试确实可以非常有效地记录您对代码的理解,假设和推理,而且会自动提醒您使它们与代码保持同步每当你打破它们时(好吧,只要你实际用你的构建运行它们......).

Answer 2

我不认为你可以正常编写没有评论的代码.

简而言之,代码文档如何.评论记录了原因.

我希望这些评论能够表明代码编写的条件,需求或外部因素所带来的限制,更改代码所带来的影响以及其他问题.注释包含代码本身未包含的信息.

Answer 3

代码中的注释应该告诉你为什么你最初以某种方式做某事.这并不意味着代码太难理解.