Coding style “你的”是什么；硬性规定”；关于注释代码？

我已经看到了其他问题，但我仍然对这个主题的涵盖方式不满意

我想提取一份详细清单，以便在代码检查时查看注释。

---

我相信人们会说一些相互抵消的话。但是，嘿，也许我们可以为每个营地建立一个列表。对于那些根本不发表评论的人，列表将非常简短：）

如果评论过期（与代码不匹配），请将其删除或更新。永远不要留下不准确的评论

文件就像性；当天气好的时候 很好，非常非常好，什么时候 这很糟糕，总比什么都没有好

---

尽可能编写自解释的可读代码。当您必须编写过于复杂而一眼就看不懂的代码时，请添加注释。还可以添加注释来描述您编写的代码背后的业务目的，以便于将来维护/重构。

在实现RFC或其他协议规范时，请使用规范对应的部分注释状态机/事件处理程序等。确保列出规范的版本或日期，以防以后修改。

我写了一篇关于不好评论的完整文章。享受：）

---

您所写的注释可以揭示代码的质量。我无数次删除代码中的注释，以更好、更清晰的代码替换它们。为此，我遵循两条反评论规则：

• 如果您的注释仅仅解释了一行代码，那么您应该让这行代码自己说话，或者将其拆分为更简单的组件
• 如果您的注释解释了函数中的一段代码，那么您可能应该解释一个新函数

在两种不同的情况下，这些规则实际上是相同的

我遵循的另一个更正常的规则是：

• 使用动态类型语言时，记录重要函数对其参数的期望，以及调用方对返回值的期望。重要函数是那些将有非本地调用方的函数
• 当您的逻辑由另一个组件的行为决定时，最好记录您对该组件的理解和期望

我用元注释注释公共或受保护的函数，如果我记得的话，通常会点击私有函数

我解释了为什么存在任何足够复杂的代码块（判断调用）。为什么是最重要的部分

如果我写的代码我认为不是最优的，我会发表评论，但我会保留它，因为我无法找到更聪明的方法，或者我知道我以后会进行重构

我发表评论是为了提醒自己或他人代码中没有的功能缺失或即将出现的需求代码（TODO等）

我通过注释来解释与类或代码块相关的复杂业务规则。大家都知道我写了好几段，以确保下一个男生/女生知道我为什么要写一百行的课

---

仅限步行前；说明一个类的单一职责、任何注释或注释以及更改日志。至于方法，如果任何方法需要大量的注释，那么是时候重构了。

关于注释，我有一条简单的规则：你的代码应该讲述你正在做的事情；你的评论应该说明你为什么要这么做

---

通过这种方式，我确保继承我的代码的人能够理解代码背后的意图。

我记录了类中的每个类、每个函数和每个变量。简单的docblock是前进的方向

一般来说，我写这些docblock更多的是为了自动化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
     *
     */

---

而且，如果某些东西以某种方式做某些事情的原因不是不言自明的，我会在你写评论的时候评论一下，停下来，反思一下，问问自己是否可以修改代码，这样就不需要评论了。您能否更改一些变量、类或方法名称以使事情更清楚？一些

断言

s或其他错误检查是否会将您的意图或期望编码？你能把一些很长的代码分割成清晰命名的方法或函数吗？注释通常反映了我们无法清晰地编写（a-hem、代码）。用计算机语言写清楚并不总是容易的，但需要一些时间来尝试。。。因为代码从不说谎

---

另外，你在“硬规则”周围使用引号的事实很能说明问题。未强制执行的规则不是“硬规则”，唯一强制执行的规则是在代码中。

我通常在编写方法之前对其进行注释。我将为函数中需要执行的每个步骤编写一行或两行注释，然后在注释之间编写代码。当我完成时，代码已经被注释了

---

最重要的是，在我编写代码之前，它已经被注释过了，所以在注释中没有对以前的知识进行不合理的假设；一、 我自己在写代码的时候对代码一无所知。这意味着它们往往很容易理解，正如它们应该理解的那样。

没有硬性规则——硬性规则导致教条，人们通常在不够聪明，不能独立思考时遵循教条

指南我遵循：

1/注释说明正在做什么，代码说明如何做-不要重复您的工作

2/注释应指代码块，而不是每行。其中包括解释整个文件、整个函数或只是一段复杂代码的注释

---

3/如果我认为我会在一年后回来，并且不理解代码/注释的组合，那么我的注释还不够好。

我会在总结我所做工作的代码块中添加一条注释。这有助于那些

// 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");