Question

我的代码中有一个if (a > b) { ..，我想解释为什么有人在查看代码。

它存在的原因相当复杂，如果不使用图像就无法解释。

问题是，如何最好地将这个文档记录给查看代码的程序员？有普遍接受的方式吗？

我应该在代码中创建一条评论“看XX解释”，然后在某处创建一个包含XX的文档吗？

Answer 1

这很大程度上取决于你编码的内容和项目的大小，但通常我会说你应该只针对if (a > b) { ..正在检查的内容和为什么。

当你到达if条件中的内容时，请解释一下。关于函数本身及其目标的更广泛的解释通常应该在声明中，尽管你也可以在定义中添加描述（我更喜欢一般地避免这种情况，尽管我有时会更详细地描述这个方法。定义，它会简单地混淆类的声明。）

例如，

class A
{
// this method performs operations on x or y as appropriate, given the input conditions of
// a and b. Its purpose is ... and in order to achieve this it does ...
void Method(int a, int b);
};

// elsewhere in a .cpp file

// Note that this method uses method abc rather than method cde in order to achieve
// such and such more efficiently (description here is more technical than in the
// declaration, and might focus on more specific issues while still remaining 
// applicable to the function as a whole, and should therefore not be in the body)
void A::Method(int a, int b)
{
    // check to see whether or not a > b in order to decide whether to operate on x or on y
    if (a > b)
    {
      // a is greater than b, and therefore we need to operate on x because...
    }
    else
    {
      // a is not greater than b, therefore we need to operate on y because...
    }
}

我发现通过构建我的注释来解决代码的特定部分就是这样的原因，读者能够“跟踪代码在她阅读时所讲述的故事”。

如果在没有更广泛解释的情况下完全无法描述if部分正在做什么，那么无论如何都要添加一个或两个段落。长评论没有任何问题，只要它们处于良好位置并解决以下代码行的特定目的。您不需要添加以获取更多信息，请参阅函数标题，因为这应该已经隐含了。

您可以为封闭的函数，方法或范围添加更广泛的描述，但注释应始终尽可能简洁地解决它们所指的代码段。毕竟，如果读者想知道整个功能在做什么，她会看一下声明。她正在查看函数定义的原因是因为她想知道函数的组件正在做什么，所以评论应该只解决这个问题。

如何评论具有复杂解释的代码

1 个答案: