python注释_日志消息是可执行代码和注释

python注释

尽管在一个人的代码中应添加多少注释之间存在意见分歧，但我认为可以肯定地说，大多数开发人员都同意以下代码段中的注释是多余的：

// increment the total
total++;

在该示例中，代码很简单，并且实际上是不言自明的，用标准的Java运算符递增了一个体面命名的变量total 。 幸运的是，我现在没有像以前那样看到明显不必要的评论类型。

我仍然在其中似乎比我更希望看到多余注释的一个方面与导致解释性日志语句的代码情况相关。 尤其是当导致log语句的情况有些棘手时，似乎有时会希望向将来将要阅读和维护该代码的开发人员写评论，并希望记录相关信息以供使用。在以后调试特殊条件时。 在大多数情况下，精心设计的日志消息(如其他精心设计的可执行代码)可以说明一切，而无需其他注释。

尽管编写自我记录的日志记录代码与编写自我记录的任何可执行代码在很大程度上相似，但是日志记录代码具有能够在日志消息中表达任意详细信息的优点。 普通代码受编程语言支持的结构的限制，并且有时语言的结构可能不如人们希望的那样表达意图。 记录的消息在可表达的内容方面的限制要少得多。 不利的一面是，更改代码后，记录的消息通常更容易被忽略。 必须进行代码更改，但是日志消息通常可以保持不变(即使它们应该已经更改)，并且直到将来某个时候记录该语句时，才会注意到这种遗漏。 尽管如此，与注释相比，已记录的消息具有更好的机会来进行更改/更新，而注释仅在代码读取期间才被公开。

使用日志消息来表达特殊条件而不是代码注释的附带好处是，这可以导致编写简洁而透彻的日志消息时需要遵守更多纪律。 通过记录的消息而不是代码内注释进行“注释”的另一个好处是，可以在情况发生时在运行时编写消息，并提供对代码行为的宝贵见解，而这些行为在分析静态代码时根本不可用。

以下是两个代码清单，一个使用代码内注释，另一个使用日志记录，以表达对将来维护此代码的开发人员相同的看法。 在这两种情况下，都有记录的业务逻辑考虑因素是，2016年国家橄榄球联盟(NFL)超级碗(丹佛野马队获胜)没有使用传统的罗马数字命名约定来命名。 它没有像以前的超级碗那样被冠以“ L”的称号，而是被冠以“ 50”的称号。 这是业务逻辑规则类型的精心设计的示例，通常以代码注释形式表示。 第10行是此处列出的每个代码的重点。

private int convertToSuperBowlYear(final String superBowlNumber)
{
   int superBowlYear;
   if (superBowlNumber == null || superBowlNumber.isEmpty())
   {
      superBowlYear = 0;
   }
   else if (superBowlNumber.equals("L"))
   {
      // Super Bowl 50 was not named with the conventional Roman Numeral, so using '50' instead of 'L'
      superBowlYear = 2016;
   }
   else
   {
      superBowlYear = getSuperBowlYearFromNumber(getDecimalNumber(superBowlNumber));
   }
   return superBowlYear;
}

private int convertToSuperBowlYear(final String superBowlNumber)
{
   int superBowlYear;
   if (superBowlNumber == null || superBowlNumber.isEmpty())
   {
      superBowlYear = 0;
   }
   else if (superBowlNumber.equals("L"))
   {
      logger.fine("Super Bowl 50 was not named with the conventional Roman Numeral, so using '50' instead of 'L'.");
      superBowlYear = 2016;
   }
   else
   {
      superBowlYear = getSuperBowlYearFromNumber(getDecimalNumber(superBowlNumber));
   }
   return superBowlYear;
}

这里未显示方法getSuperBowlYearFromNumber(int)和getDecimalNumber(String)实现，因为它们对本次讨论不重要。 此处重要的是，“ L”不是有效的超级碗编号，因此在确定超级碗的年份时必须使用“ 50”而不是“ L”。 如果开发人员不熟悉NFL或它的超级碗命名约定，并且不熟悉2016年超级碗的命名约定，则需要某种类型的注释来理解为什么一个超级碗与其他超级碗区别对待。

作为旁注并谈到罗马数字，令人惊讶的是，网络上有多少Java代码示例可用于在罗马数字和基于十进制的整数之间进行转换。 其中一些包括将罗马数字转换为小数，将罗马数字转换为介于1到3999之间的十进制，使用Java将罗马数字转换为十进制，在Java中将罗马数字转换为十进制以及如何将罗马数字转换为整数。 我怀疑有很多家庭作业问题会激发大量的代码示例。

Alexey最近发表了博客文章“ 用警告日志消息替换代码中的TODO注释？ 他指出，在以前曾写过“ TODO”注释的情况下，他已开始编写警告和错误级别日志消息。 这是使用日志消息代替注释的更具体，更明显的示例。 就阿列克谢而言，他之所以这样做，是因为他意识到自己“总是忘记”“待办事项”，而且“很少被发现，而且几乎永远无法解决”。 Alexey的结论是：“这就是为什么我建议您尝试通过在日志中写下您的评论，您的想法甚至是您的疑问来尝试这种方法：这将帮助您，甚至可以使您和您的同事开心！”

在某些情况下，可能添加到源注释中的内容可能不适合添加到日志消息中。 这种情况包括评论的冗长或评论的敏感性。 还值得注意的是，某些注释级别的已记录消息可能永远不会被记录，因为它们的日志级别设置得如此具体，以致在代码执行过程中永远不会真正启用该日志级别。 但是，在许多情况下，使用简洁而透彻的日志消息而不是代码内注释来与将来的开发人员和您将来的自己进行通信具有优势。

翻译自: https://www.javacodegeeks.com/2017/12/log-message-executable-code-comment.html

python注释