你的个人方式/评论是什么？
重复
你有什么关于评论的硬性规定？
与我合作的开发者有一些关于评论的话，这对我来说很有意思（见下文）。 你的个人方式/评论是什么？
“我不会为代码添加评论，除非它有一个简单的标题或有一个标题
平台错误或必要的解决方法，这并不明显。 代码可能会改变，评论可能会引起误解。 代码应该是
自我记录使用描述性名称及其逻辑
组织 - 其解决方案应该是最干净/最简单的方式
执行一个给定的任务。 如果程序员不能告诉程序是什么
只通过阅读代码，然后他没有准备好改变它。
评论往往是写一些复杂或复杂的拐杖
非显而易见 - 我的目标是始终编写干净而简单的代码。“
“我认为在评论时有几个阵营，那些认为他们正在编写一个API的企业类型，以及一些代码将会用于后代的工匠类程序员，他认为代码说什么它比评论更清晰，而新手编写冗长/不清晰的代码，以便需要为自己留下笔记，说明他们为什么要做某些事情。“
“自我记录代码”理论存在一个悲剧性的缺陷。 是的，阅读代码会告诉你它到底在做什么。 但是，代码无法告诉你应该做什么。
我认为可以肯定地说，当代码没有做它应该做的事时，所有的错误都会导致:)。 因此，如果我们添加一些关键评论来向维护人员提供足够的信息以知道代码应该做什么，那么我们已经赋予他们修复大量错误的能力。
这给我们留下了多少评论意见的问题。如果您发表太多评论，事情就会变得冗长乏味，评论将不可避免地与代码过时。 如果投入太少，那么它们并不是特别有用。
我发现定期评论在以下地方最有用：
1）.h或.cpp文件顶部的简要描述，用于解释类的用途。 这有助于维护人员快速浏览，而无需筛选所有代码。
2）实现非平凡函数之前的注释块，解释其目的并详细说明其期望输入，潜在输出以及调用该函数时期望的任何古怪。 这节省了未来的维护人员不必破译整个函数来解决这些问题。
除此之外，我倾向于评论任何可能让某人感到困惑或奇怪的东西。 例如：“这个数组是基于1的，而不是基于等于0的数据”。
写得好，评论很好，非常宝贵。 糟糕的评论往往比没有评论更糟。 对我而言，缺乏任何评论意味着代码作者的懒惰和/或傲慢。 无论你的代码在做什么或者代码有多么棒，对你来说是一件很有挑战性的任务，它会让你陷入一团糟的代码中，并弄清楚到底发生了什么。 做得好的评论可以让人们了解现有代码的速度。
我一直很喜欢Refactoring对评论的看法：
我们在这里提到评论的原因是评论通常被用作除臭剂。 令人惊讶的是，您经常查看代码厚度较大的代码，并注意到代码不正确，因此评论在那里。
评论导致我们看到了糟糕的代码，这些代码有我们在本章其余部分讨论过的所有糟糕的代码。 我们的第一个行动是通过重构消除不良气味。 当我们完成时，我们经常发现评论是多余的。
尽管这是有争议的，但对于我读过的代码来说，它是正确的。 公平地说，福勒并不是说不要评论，而是要在你做之前先考虑你的代码的状态。
为了本地理解代码，您需要文档（以某种形式;并非总是注释）。 代码本身告诉你它做了什么，如果你阅读所有的代码并且能够牢记这一点。 （更多关于下面的内容。）评论最适合非正式或半正式文档。
许多人说评论是一种代码味道，可以通过重构，更好的命名和测试来替代。 虽然评论（这是军团）的评论不错，但总结起来很容易，哈利路亚也没有更多的评论。 这使得本地文档的所有负担 - 我认为 - 太多了 - 在命名和测试上。
记录每个函数的合约，以及对于每种类型的对象，它代表什么以及对有效表示（技术上讲，抽象函数和表示形式不变）的任何约束。 在可行的地方使用可执行的，可测试的文档（doctests，单元测试，断言），但也可以写简短的评论给出有用的依据。 （如果测试采用示例的形式，它们不完整;它们在哪里完成，哪些是精确的合同，它们可以和代码本身一样多。）为每个模块和每个项目编写顶级注释; 这些可以解释保留所有其他评论（和代码）的约定。 （这支持命名为文档：随着约定的建立，我们可以期待找到一些细节，我们可以更经常地确信这些名字能够告诉我们所需要知道的所有内容。）更长，更风格化，更刺激的冗余Javadocs拥有它们使用，但帮助产生了反弹。
（例如，这个：
执行n倍折叠。
@参数n闪烁的次数
@param x frobulation中心的x坐标
@参数frobulation中心的y坐标
@param z frobulation中心的z坐标
可以像“围绕中心（x，y，z）n次frobulate”。 评论不一定是阅读和写作的麻烦。）
我并不总是这样说; 这取决于我对代码的价值以及期望读者的价值。 但是学习如何写这种方式使我成为了一个更好的程序员，即使是在偷工减料的时候。
回到我们为了本地理解而记录的声明：这个函数做了什么？
def is_even(n): return is_odd(n-1)
测试一个整数是否是偶数？ 如果is_odd()测试一个整数是否为奇数，那么是的，这是有效的。 假设我们有这个：
def is_odd(n): return is_even(n-1)
同样的推理说这is_odd()测试一个整数是否是奇数。 当然，把它们放在一起，即使它们每一个都起作用，它们都不起作用。 改变一下，我们会有代码可以工作，但只能用于自然数，而在本地看起来像是用于整数。 在这个微观世界里，理解代码库就像是：跟踪周围的依赖关系，尝试对假设进行反向工程，作者可能会在一两行中解释他们是否打扰了他们。 我讨厌在过去的几十年中不小心的编程人员让我这样做的精神代价：噢，这种方法看起来像是有着远远超过warpcore的副作用...总是？ 那么，至少，如果奇怪的crobuncles至少饱受折磨; 他们呢？ 更好地检查所有crobuncle处理代码......这将对理解构成自己的挑战。 良好的文档会将这个O（n）指针追踪到O（1）：例如，知道函数的契约以及它明确使用的契约，函数的代码在没有系统知识的情况下应该是有意义的。 （在这里，说is_even()和is_odd()工作在自然数上的契约会告诉我们这两个函数都需要测试n==0 ）