只给不常见的代码添加注释

|

我听到有人说注释应该解释原因，虽然这本身并没有 “错”，但我不记得这是我写注释的主要原因。下面是我在当前代码库中写的一些注释。这并不是我写的唯一一种注释，但这种风格与我听到的别人的建议有所不同。

非惯用代码注释

此注释位于我的 FontLoad 函数中，该函数将字体文件中的字形放入位图中，以便我将其转换为纹理并渲染到屏幕上。该注释位于遍历文件中所有字形的循环的起始位置，字形是一个 32 位 int。

//跳过控制代码和私人使用区域
if（glyph < ' ' || (glyph >= 0xE000 && glyph <= 0xF8FF) || (glyph >= 0xF0000)) {

如果我想解释原因，我会写控制代码是不可见的，而且程序中不使用私人使用的字形，但很明显，这不是我写的，也不是我发表评论的原因。

这里不寻常的（或者说不习惯的）是 E000、F8FF 和 F0000 这些字面。通常情况下，我会为字面量命名，但在整个程序中只使用了一次。我不想花三行来创建只用一次的常量，所以我写了一个注释。为什么 “在这里没有任何价值。如果我们在程序中加入控制代码或私人使用的字形，程序就不会出现异常。如果这个函数被复制到一个新的项目中，看到一个注释暗示不使用私人区域字体，而实际上使用了，那会让人很困惑。我坚持对字面进行解释，因为这是该行中唯一不寻常的部分。

在同一函数的后面，我写道 if (w && h) { //has pixels 看到这个 if 语句非常奇怪，会让很多人怀疑是否有错别字，以及为什么会有这个 if 语句。字体文件中的字形可以没有像素数据，这可能会让人感到惊讶。不过，从函数的其余部分来看，这条注释非常清楚。它表明存在字形没有像素的情况，而在将字体加载到位图的函数中，我们不需要尝试加载没有像素的字形。

下一条注释出现在我实现的一个结构体的比较函数中。

return v < 0 ? 1 : v ? -1 : 0; //想要降序，所以我们使用 -1 而不是 1

该结构只在一个文件中可见，并且只在一个函数中使用。该函数不返回结构体，也不接受结构体作为参数。我有一个包含该结构的数组，我需要对它进行排序，并且需要它以降序排列。通常情况下，在编写比较函数时，都是按升序排列的，而且对象通常会在多个函数中使用。这种情况很奇怪，我想留下注释，说明降序是有意为之。

如果注释太短或不够好怎么办？

假设代码没有问题，变量也命名得很好，你仍然可能会遇到难以理解的非惯用代码。如果是这种情况，我强烈建议在函数外或函数开头加上多行注释，完整解释函数应该做什么。在代码中间加上解释会让人难以理解。在代码中夹杂解释会使代码更难阅读。如果函数正在实现一种算法或规范，请将其链接起来。

如果您无法理解函数应该做什么，那么您就真的无法更改它，至少在不猜测的情况下无法更改，而猜测是绝对不应该做的事情。另外，你还可以尝试

  • 让函数/类只在一个文件中可见，这样人们一般就不需要与它交互。
  • 将该函数标记为废弃函数，并推荐替代方法。
  • 改进测试/示例，以便人们可以查看使用情况。
  • 更改变量名，使其对不熟悉该领域的人更友好。
  • 在文件顶部链接该领域的书籍/阅读材料。
  • 说明为什么选择函数中的算法。也许人们只是为了了解函数的功能。如果是这样，说明为什么选择这种算法就足够了。
  • 重构代码并编写单元测试。这将降低修改破坏系统或浪费调试时间的可能性。

如果上述方法都失败了，而你理解代码，但你的同事却不理解，我想你可以评论一下原因。但我无法想象如果以上都失败了，成功率会有多高。

我写的代码一般都是实验性的，经常被扔掉。通常情况下，代码并不完美，也不是自始至终都是成语。每当注释变得陈旧时，我发现上述风格既清晰又不会造成混乱。这些简短的注释对我很有用，因为它们足够短，不会让我脱离阅读代码的流程。

本文文字及图片出自 Comment Non-Idiomatic Code

你也许感兴趣的：

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注