我见过的其他问题，但我仍然不满意这个主题覆盖的方式 。
我想提取的东西distiled清单在代码检查，检查的意见。
我相信人们会说的东西，只会相互抵消。 但是，嘿，也许我们可以建立各个阵营的列表。 对于那些谁没有在所有的列表评论也只是很短的:)
Answer 1:
我有一个评论简单的规则：你的代码应该告诉你正在做什么的故事; 您的评论应该告诉你为什么做它的故事。
这样一来，我要确保无论谁接手我的代码将能够理解的代码背后的意图。
Answer 2:
- 我评论的公共或受保护的功能与元意见，通常打私职能，如果我还记得。
- 我的评论为什么任何足够复杂的代码块存在（主观判断）。 该为什么是重要的组成部分。
- 我评论，如果我写的代码，我认为不是最佳，但我离开它，因为我不能想出一个聪明的方法或我知道我将在后面重构。
- 我的评论提醒自己或他人丢失的代码（TODO等）不存在的功能或即将到来的要求代码。
- 我的评论讲解有关类或代码块复杂的业务规则。 我已经知道写了好几段，以确保未来的家伙/加仑知道为什么我写了一百行类。
Answer 3:
如果注释是过时的（不代码一致），删除或更新。 千万不要留在原地不准确的评论。
Answer 4:
写可读代码是不言自明的尽可能。 发表评论时，你必须编写代码过于复杂，在一看就懂。 此外，添加注释来描述代码背后的经营宗旨是你写的，更容易维护/在未来重构它。
Answer 5:
文档是像性; 当它的好，这是非常，非常好，当它是坏的，这总比没有好
Answer 6:
当实现一个RFC或其他协议规范，注释状态机/事件处理程序/等与它们对应于该规范的部分。 确保列出规范的版本或日期，如果它是后来修改。
Answer 7:
你写的评论可以揭示你的代码的质量。 我无数次在我的代码以更好，更清晰的代码来替换他们已经删除评论。 为此，我跟着一对夫妇的反注释规则：
- 如果您的评论仅仅解释了一行代码，您应该让该行代码自己说话或把它分解成简单的组件。
- 如果您的评论解释函数内的代码块，你应该是解释一个新的函数。
这些都是真的重复了两个不同的上下文相同的规则。
另外，比较正常的规则，我遵循如下：
- 当使用动态类型语言，记录了预期的重要功能做出自己的论点，以及期望呼叫者可以对返回值。 重要的功能是那些永远不会有非本地来电。
- 当你的逻辑是由另一个组件的行为决定的，这是很好的记录你的理解，但该组件的期望。
Answer 8:
我通常评论的方法之前，我把它写。 我会写一个的每一步，我需要把函数中的注释两行，然后我写的注释之间的代码。 当我完成后，该代码已经评论。
有关的很大一部分是之前我写的代码它的评论，所以没有有关在评论以前的知识不合理假设; 我自己，也不知道，我的代码时，我写了他们。 这意味着，他们往往是容易理解的，因为他们应该的。
Answer 9:
我写了差评一个完整的文章。 请享用 ：）
如何坏的评论都诞生在你的代码
Answer 10:
没有硬性的规则 - 硬性规则导致教条和人们一般遵循教条时，他们没有足够的智慧为自己着想。
该指引我如下：
1 /意见告诉正在做什么，代码告诉它如何被做 - 不重复你的努力。
2 /注释应该指的代码，而不是每个行块。 这包括解释整个文件，全功能或代码只是一个复杂的片段意见。
3 /如果我想，我会回来的一年，不理解的代码/注释组合，然后我的意见是不够好还。
Answer 11:
征求意见一个伟大的规则：如果你正在读通过代码试图找出东西出来，并评论的地方就会给你答案， 把它放在那里，当你知道答案 。
只有这些时间调查一次 。
最终，你会知道你写 ，你需要离开指导的地方，那是十分明显的，以独立的地方。 到那时，你会花时间通过您的代码拖网试图弄清楚为什么你做了:)
Answer 12:
我记录每一次课，每一个功能，一个类中的每一个变量。 简单的文档块是前进的方向。
我一般会写这些文档块更多的比什么都自动化API文档...
例如，我的PHP类之一的第一部分
/**
* Class to clean variables
*
* @package Majyk
* @author Martin Meredith <martin@sourceguru.net>
* @licence GPL (v2 or later)
* @copyright Copyright (c) 2008 Martin Meredith <martin@sourceguru.net>
* @version 0.1
*/
class Majyk_Filter
{
/**
* Class Constants for Cleaning Types
*/
const Integer = 1;
const PositiveInteger = 2;
const String = 3;
const NoHTML = 4;
const DBEscapeString = 5;
const NotNegativeInteger = 6;
/**
* Do the cleaning
*
* @param integer Type of Cleaning (as defined by constants)
* @param mixed Value to be cleaned
*
* @return mixed Cleaned Variable
*
*/
但后来，我就有时也记录显著代码（从我的init.php
// Register the Auto-Loader
spl_autoload_register("majyk_autoload");
// Add an Exception Handler.
set_exception_handler(array('Majyk_ExceptionHandler', 'handle_exception'));
// Turn Errors into Exceptions
set_error_handler(array('Majyk_ExceptionHandler', 'error_to_exception'), E_ALL);
// Add the generic Auto-Loader to the auto-loader stack
spl_autoload_register("spl_autoload");
而且，如果它不言自明为什么有些东西东西在一定的方式，我会评论说，
Answer 13:
我在我的代码开始创建注释块，挂牌程序的目的，它的创建之日起，任何许可/版权信息（如GPL），以及版本历史记录。
我常常评论我的进口，如果他们为什么被进口不是很明显，特别是在总体方案似乎并不需要进口。
我一个文档字符串添加到每个类，方法或函数，描述什么块的目的，我认为任何额外的信息是必要的。
我通常有针对相关的部分，例如widget创建，变量等分界线由于我使用SPE我的编程环境，它会自动突出显示这些路段，使导航更加容易。
我添加TODO注释的提醒，而我的编码。 这是提醒自己，一旦通过验证，才能正常工作重构代码的好方法。
最后，我的评论可能需要一些澄清或以其他方式需要一些元数据为自己在未来或其他程序员个别线路。
就个人而言，我不喜欢看代码，并试图找出什么它应该做的事。 如果有人可以只写一个简单的句子来解释它，生活更容易。 自记录代码是用词不当，在我的书。
Answer 14:
我注重的原因 。 因为什么往往容易读取。 TODO的也很棒，他们节省了大量的时间。
我记录的接口（例如文件格式）。
Answer 15:
仅前同步码; 声明一个类的单一责任，任何说明或注释，并更改日志。 至于方法，如果任何方法需要大量的评论，现在是时候重构。
Answer 16:
当你写评论，停止，反映和问自己，如果让不需要的评论，你可以更改代码。 你可以改变一些变量，类或方法的名称，使事情更清晰？ 将一些assert S或其它错误检查编纂你的意图或期望？ 你可以的代码一些长款分成明确命名方法或函数？ 评论通常都是我们不能写（一个下摆，代码）明确的反映。 这并不总是易于与计算机语言写清楚，但需要一定的时间去尝试......因为代码从不说谎。
PS您使用围绕“硬规则”的报价的事实告诉。 未强制执行的规则都没有“硬规则”和强制执行的唯一规则是在代码中。
Answer 17:
我加1个注释的代码块，总结我在做什么。 这有助于谁是寻找特定的功能或代码段的人。
我的评论任何复杂的算法，或过程中，不能在第一眼想通了。
我签我的代码。
Answer 18:
唯一可以保证的地方，我发表评论：TODO部分。 最好的地方，保持跟踪的事情需要返工是正确的，在代码。
Answer 19:
在我看来，TODO / TBD / FIXME等都是确定有其中当前正在处理的代码，但是当你看到尚未触及的5年中充满了这些代码，你就会意识到，这是一个相当确保东西拿不动的烂路。 总之， 在注释TODO注释倾向于呆在那里 。 更好的，如果你有事情需要被固定在某个时候使用一个错误追踪系统。
哈德森（CI服务器）有一个伟大的插件，扫描待办事项，并注意到有多少在你的代码。 你可以，如果有太多造成的构建，甚至设置的阈值被归类为不稳定。
我最喜欢的规则的拇指关于意见是： 如果代码和注释不一致，那么它们可能会选择不正确
Answer 20:
一个非常重要的事情来检查时，你正在检查头文件（或者无论你怎么称呼方法声明之前的块）是指令和注意事项很容易发现。
指令是任何“做”或“不做”，会影响客户端的说明：不从UI线程调用，不要在性能关键代码中使用，Y前致电X，释放返回值使用后，等
注意事项是什么，这可能是一个讨厌的惊喜：剩余行动项目，被誉为假设和限制，等等。
当你专注于你正在编写和检查的方法，你会看到的一切。 当程序员使用你的方法和三十人在一个小时内，你不能指望一个彻底的读取。 我可以给你研究的数据，如果你有兴趣。
Answer 21:
我们写了评论（实际上，我已经做了一些）这里的文章： http://agileinaflash.blogspot.com/2009/04/rules-for-commenting.html
这真的很简单：注释被写入告诉你的代码不能。
这导致了一个简单的过程： - 输入你想在第一次发表任何评论。 - 改进代码，以便注释变得多余 - 删除现在冗余评论。 - 只有承诺有没有多余的评论代码
文章来源: What are your “hard rules” about commenting your code?
