做酒水网站陕西有哪些,wordpress 获取文章时间,nginx代理wordpress,自己做电影网站需要什么有什么比花时间写注释更令人感到兴奋的事情吗#xff1f;如果我没有猜错#xff0c;你可能会说#xff1a;“不好意思#xff0c;所有事情都比写注释更令人感到兴奋”。如果有人要你给代码加上注释#xff0c;对你来说就像是一种侮辱。你的代码写得如此优雅#xff0c;它…有什么比花时间写注释更令人感到兴奋的事情吗如果我没有猜错你可能会说“不好意思所有事情都比写注释更令人感到兴奋”。如果有人要你给代码加上注释对你来说就像是一种侮辱。你的代码写得如此优雅它已经足以说明它要做的事情注释是多余的代码就是一切。
无论是开源项目还是专业软件开发代码注释通常有两种形式要么没有和要么毫无用处。任何领域或使用任何编程语言的程序员无论他们来自世界的哪个地方似乎都不喜欢给代码写注释。如果你想讲故事可能会选择不同的人生道路比如去当作家。
这种不情愿甚至形成了某种范式和哲学观点认为代码注释实际上是有害的任何试图逃避它的人现在都可以愉快地重新讨论这些主张。但是稍微夸张一点说我们实际上是在用这种方式破坏信息。虽然代码注释有时候确实会适得其反但真正有害的是我们对它的看法。
说到底代码注释就像是错误处理我们很早就被告知它很重要但却无法理解其中的原因。我们越来越厌烦为同样的老师、主管或烦人的队友做这件事。但就像错误处理一样如果做得好我们就是从中获益最多的人。但要做到这一点我们需要面对一些严酷的事实并承认根本不存在所谓的自解释代码。
所以让我们来戳破其中的一些泡沫吧
自解释的代码是不存在的
反对给代码写注释的人认为“代码应该好到不需要任何多余的解释”。好的代码确实不需要注释来描述变量或函数是干什么用的。
// bad start:int a 4 * OFFSET;// but dont use a comment to tell what it does:int a 4 * OFFSET; // initial foo value// instead choose a name telling it itself:int initial_foo 4 * OFFSET;
确实有意义的变量名根本不需要注释但这实际上更像是一种体面的编码风格而不是文档。当这种片面的观点变成反对使用代码注释的普遍理由时问题就出现了。
问题是即使变量、方法、类、函数、模块的名称是自解释的但这些并不能描述出代码的全局面貌也不一定能说明各部分代码为什么要那么写。当然清晰的实现往往会让我们产生一种错觉认为不需要再写注释了。当你花了几个小时甚至几天时间解决了手头的问题那些代码在当下可能是完美的然后你把它们打包、提交。
但是一个月后会怎样你能记住多少细节它们还是那么有意义吗
软件开发困难重重
当然有人可能会争辩说“代码就在那里你看一下就明白了”。如果我们说的是某块代码是干什么用的那么或许这么说是有道理的。但对于任何超出这个范围的东西深挖代码可能是在浪费时间就像在阅读一本没有索引的书你要从头读起才可能找到你需要的东西。
而且这不仅仅是为了了解别人的代码或者向别人解释你的想法。当你重新查看旧代码或者修复错误时你的脑子里是不是经常犯嘀咕或者因为 git blame 显示了你的名字而感到惊讶然而再往后它们可能被忘得一干二净然后你会再次相信一切都应该是自解释的所有的细节都应该是明确无误的。
无论你怎么努力软件本身并不会完全自解释。这既不是你的错我也不是想要质疑你的能力这与人类本身有关我们低估了软件的复杂性而且人类的思维具有波动性。注释的目的不是为了指出代码中存在的缺陷而是为了抵制编程语言本身存在的缺点。即使是最干净的代码也不可能自己解释写代码的人在写代码时在想些什么。有可能一切都是完美的但仍然会出错。注释并不是干净代码的替代方法而是代码的固有组成部分。
代码注释解析
在进一步讨论我们的问题之前先让我们来看看不同的代码注释风格。
/*** Javadoc-style documentation comment.*/void foo(void) {if (bar \u0026gt; 10) {/* regular comment */...}}
常规注释就是编程语言本身定义的注释。根据经验它们不应该被广泛使用因为它们倾向于用来解释代码在做什么。
另一方面文档注释从外部角度描述了全局变量、函数和模块。在函数体内部它们基本上就是常规注释工具通常会忽略它们。如果在函数内部有一些值得描述的东西看看是否可以把它们放进函数描述本身。
文档注释本质上就是常规注释加上一些额外的附件例如额外的正斜杠/// doc comment、感叹号//! doc comment或者/*! multiline doc comment /或者Javadoc注释中的附加星号/* doc comment */。实际上其他编程语言和工具也支持Javadoc所以这里就以它为例子。
当然你也可以使用常规注释并忘掉那些时髦的标签。不过一些文档生成器如 Doxygen 或 Sphinx可以直接根据注释创建 PDF、HTML 或手册页大多数现代 IDE 为它们提供了额外的显示支持省得你老是进行上下文切换而且还可以为你提供一些有用的信息。
除了注释的后处理之外注释的格式并不重要重要的是你想要表达什么。
冗余的注释聚焦在错误的信息上
我们已经得出结论即不应该记录代码在做什么而是记录为什么要这么做以及怎样做但这究竟意味着什么呢
人们不喜欢写注释的一个常见原因是“它们只是在陈述已经很明显的东西”所以注释是多余的。对于一般性的注释确实难以反驳特别是在面向对象语言的封装方面。一些简单的函数比如 get_temperature() 的一般性描述可能如下所示
/*** Returns the temperature.*/int get_temperature(void) {return temperature;}
这里的注释确实没有增加太多的价值它本质上只是重复了函数的名字只是在说明这个函数的作用。这不是我们想要的我们想要的是代码没有告诉我们的东西。
这个函数非常简单所以写注释是绝对没有必要的。但话又说回来软件开发当中没有什么东西是真正简单的。如果你够仔细就会发现每个函数都有值得写的东西而这些东西并不能从它的名字甚至是简单的一两行代码中看出来。
/*** Returns the temperature in tenth degrees Celsius* in range [0..1000], or -1 in case of an error.** The temperature itself is set in the periodically* executed read_temperature() function.** Make sure to call init_adc() before calling this* function here, or you will get undefined data.*/int get_temperature(void) {return temperature;}
事实证明这个看似简单的函数有很多额外的信息可以写。如果只是看代码可能无法明显地看出其中的信息包括内部数据处理和程序流程。当然深挖代码最终会获得同样的信息但这样会浪费很多时间和脑力。
有人可能会说我们没办法为这些实现细节写注释。为什么要这样为什么不详细说明那些现细节让别人可以更容易地理解代码在做什么
每个函数都有自己的特点至少会有一个细节、副作用、异常、限制等等它们都值得写出来这意味着你可能需要从不同的角度来看待这个函数才能找出它们。为此你不可避免地要沉浸在代码隐藏的细节当中这样才可能发现一些之前没有想到过的特殊情况。因此代码注释不仅可以帮助读代码的人理解代码还能帮助写代码的人更好地了解代码的内部细节。
如果你确实找不到有用的信息那么应该问问自己为什么要写这些代码。这些代码存在的理由是什么而这些理由就是有用的信息。之前的例子也可以是这样
/*** Returns the temperature.** This is for testing purpose only and should* never be called from a real program.*/int get_temperature(void) {return temperature;}
请注意这段代码与之前完全相同于是这又把我们引向了另一个问题“看似自解释的代码的注释通常都很简单”它可能含糊不清可能会导致错误的假设和潜在的缺陷。指出这些细节并消除潜在的歧义对于提升代码质量来说至关重要这说明注释应该成为代码的重要组成部分。
同样如果不深入研究代码就无法发现每个函数的特点。当然在这些不起眼的细节中总有一些比另外一些更值得我们注意并不是说函数所涉及的东西都会很有趣。认知偏差的范围很广有些东西在这个时刻对你来说是显而易见的并不意味着对于其他人来说也是这样——包括未来的你。
让注释成为代码的一部分
现在我们来看看另一个人们不喜欢写代码注释的原因当代码发生改变时注释会过时。但其实这只是一个偷懒的借口在写代码时通常不会考虑将来会不会再去修改代码一旦代码被提交并合并就是确定和完美的并永远保持原样。
代码注释的另一个更大的问题是它们被视为独立于代码的东西完全与代码相分离。但如果我们将其视为代码的组成部分或者一种补充实体那么只要代码发生变化就会很自然地去调整注释。
打破恶性循环
没有人喜欢糟糕的代码注释但排斥写注释对解决这个问题并没有任何帮助。修复开发人员和代码注释之间的不正常关系是改善这种状况的唯一方法而将注释视为代码的组成部分是改善这种关系的第一步。
毫无疑问在形成这种思维方式之前需要进行练习。从长远来看这对提升代码质量来说是有益而无害的。
英文原文
https://hackaday.com/2019/03/05/good-code-documents-itself-and-other-hilarious-jokes-you-shouldnt-tell-yourself/
