1

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

它存在的原因非常复杂，如果不使用图像就无法很好地解释。

问题是，如何最好地向查看代码的程序员记录这一点？有普遍接受的方法吗？

我是否应该在代码中创建一个注释“请参阅解释 XX”，然后在某处创建一个包含 XX 的文档？

4

1 回答 1

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部分的内容，那么请务必添加一两段。长注释没有任何问题，只要它们放置得当并解决以下代码行的特定目的。您不需要添加更多信息，请参阅函数标题，因为这应该已经被暗示了。

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

于 2013-11-11T13:54:13.793 回答