每当我用任何一种语言编写典型的if-else-construct时，我都想知道（在可读性和概述方面）向其添加注释的最佳方法是什么。特别是在评论else子句时，这些评论总是让我觉得不合时宜。假设我们有一个这样的结构（示例用PHP编写）：

if ($big == true) {
    bigMagic();
} else {
    smallMagic()
}

我可以这样评论：

// check, what kind of magic should happen
if ($big == true) {
    // do some big magic stuff
    bigMagic();
} else {
    // small magic is enough
    smallMagic()
}

要么

// check, what kind of magic should happen
// do some big magic stuff
if ($big == true) {
    bigMagic();
}
// small magic is enough
else {
   smallMagic()
}

要么

// check, what kind of magic should happen
// if:   do some big magic stuff
// else: small magic is enough
if ($big == true) {
    bigMagic();
} else {
    smallMagic()
}

您对此发表评论的最佳做法是什么？

我更喜欢：

if ($magic == big) {
    bigMagic();
}
else {
    smallMagic();
}

要么：

if ($magic == big) {
    // big magic requires a big surprise, so I'm telling you about it here
    surprisingThing();
}
else {
    // give a magical feeling even if $magic is noMagicAtAll
    smallMagic();
}

除非代码中没有明确说明，否则编写注释解释您的条件检查内容似乎有点愚蠢。即使那样，最好重写代码以使其尽可能清晰。条件块的主体也是如此-如果您可以使做某件事的原因显而易见，那么请不要注释。

我不同意“从不编写注释”的理念，但我确实坚决避免使用注释来说明代码应该说的内容。如果您在代码可以说的时候写了“检查应该发生的魔术”之类的注释if ($magic == big) {...，那么读者将很快停止阅读您的注释。使用更少，更有意义的评论将使您的每条评论都具有更大的价值，并且读者更有可能关注您所写的内容。

为变量和函数选择有意义的名称很重要。精心选择的名称可以消除整个代码中解释性注释的需要。在您的示例中，$magic或者$kindOfMagic似乎比在您的示例中更好的名字，$big因为根据您的示例，正​​在测试的是“魔术”，而不是某些东西的“大”。

在代码中尽量多说。对于需要更多解释而不是合理编写代码的情况，请保留散文。

试试解释性的变量名

注释可能很棒，但是在可能的情况下，请使代码具有自我说明性。一种实现方法是使用解释性变量名。例如，而不是这样：

if (user.has_sideburns && user.can_gyrate) {
  // This user is a potential Elvis impersonator

}

我更喜欢一个命名变量：

is_potential_elvis_impersonator = user.has_sideburns && user.can_gyrate

if (is_potential_elvis_impersonator) {
  ...
}

只是为了完成一些评论：

注释的正确用法是为了弥补我们未能在代码中表达自己的意愿。请注意，我使用了失败一词。我是真的 评论总是失败。我们必须拥有它们，因为我们不能总是想出没有它们的表达方式，但是使用它们并不是值得庆祝的原因。（清洁代码由Robert C.马丁）

顺便说一句：我确实推荐这本书。

注释不应该解释代码，而应解释代码中没有的内容（更大的图片，原因，为什么未选择替代方法...）而您的示例注释就是：解释代码。

有时您可能会觉得else分支的开头需要用释义，但这通常表明您的then分支太大。

在您的特定示例中，可能不需要注释。正如Caleb所提到的，如果代码写得清楚并且变量具有语义名称，则语句不太需要注释。

将您的代码段与此进行比较：

if ($x) {
    func1();
} else {
    func2();
}

在这种情况下，您肯定希望使用注释来描述x，func1和func2代表什么（并以这种方式拍打给事物命名的人，尤其是您自己）。您甚至无法判断是否$x应该是布尔值。但这也是一种情况，如果您能够重构和重命名，则不必注释。

通常，我喜欢为逻辑块编写注释，这些注释描述了代码本身无法实现的功能。每10到20行显示一线，描述以下几行在更高的抽象水平上所完成的工作（例如，// Make the right amount of magic happen以您的示例为例）将帮助您保持专注，并让新的审阅者洞悉您的工作和时间。

实际上，我经常在开始编写代码之前就编写这些单行代码，这样我就不会丢失该段应该具有的流程。

最后，如果您确实喜欢（或有一项要求）无论代码是否可读，都应在if块中添加注释子句，我建议：

// Broad description of block
if (something) {
    //Do this because something
    something();
} else {
    //Do this because !something
    somethingElse();
}

我觉得这是最干净的，因为注释与它所涉及的代码对齐。描述什么代码的注释应尽可能接近其描述的注释。

if (IsWeekDay(day))
{// weekday -> alarm at 7am
   ...
}
else if(day == DayOfWeek.Saturday)
{// saturday -> alarm at 11am
   ...
}
else
{// (sunday) -> no alarm
   ...
}

我将括号对齐并放在括号后。

[Condition] -> [pseudo-code]

另一方面，从技术上讲，它意味着所有其他条件都失败了，因此我通常使用括号。

([Condition]) -> [pseudo-code]

注意：这是针对C＃的。

我尝试在块内使用注释来说明该块的功能（您的第一个示例）。

在使用时，这种故障会在哪里解决elseif。我使用Basic，所以没有显式的结束符，并且如果时间太长，通常必须注释条件在上面的行中进行检查（当然要换行）。

'Check XYZ
If Condition1 then
  'We need to do T and S
  DoCodeFor1();

'Check ABC
ElseIf Condition1 then
  'This requires something else to be done
  DoCodeFor2()

Else
  'We have no other option than to...
  DoCodeFor3()

End If

• 保持条件块的长度尽可能短。
• 如果看起来您的条件代码将不只是一两行简单的代码，请使用描述性好的名称来调用方法。
• 为变量使用漂亮的描述性名称。
• 确保条件语句的含义清晰，且不会混淆或冗长。如果有助于保持事物清洁和可读性，请使用一种方法。

如果以上所有方法均失败，请在if语句之前添加一个非常小的描述性注释，以阐明您的意图。否则，实际上根本不需要评论。

在C ++或C＃中，我通常不评论简单的情况（当清楚发生了什么事情时），而使用这种样式来评论最后的else ...

if (pattern == AAA)
{
  DoSomethingAAA();
}
else if (pattern == BBB)
{
  DoSomethingBBB();
}
else // if (pattern == CCC)
{
  DoSomethingCCC();
}