时间戳

首页 > 解决方案 > Xcode 中循环变量的文档注释

swift - Xcode 中循环变量的文档注释

问题描述

我知道我们可以使用

/// index variable
var i = 0

作为单个变量的文档注释。

我们如何对循环变量做同样的事情？

以下不起作用：

var array = [0]
/// index variable
for i in array.indices {
    // ...
}

或者

var array = [0]
for /** index variable */ i in array.indices {
    // ...
}

背景：

我不使用“好”变量名的原因是我正在实现一个使用数学符号派生的数值算法。在这种情况下，它只有单字母变量名。为了更好地了解派生和实现之间的联系，我使用相同的变量名。

现在我想评论代码中的变量。

标签： swiftxcodedocumentation

解决方案

如果我在 PR 中看到这样的事情，我会强烈反对。i是循环索引的广泛采用的“艺术术语”。一般来说，如果你的变量声明名需要​​注释，你需要一个更好的变量名。有一些例外，例如当它存储具有复杂用途/不变量的数据时，这些数据无法在类型系统中以更好的方式捕获。

我认为评论是初学者容易出错的一个地方，主要是被老师误导或者还没有完全理解评论的目的。不存在用于创建基于英语的伪编程语言的注释，您的整个应用程序都将在其中复制。理解编程语言是项目贡献者的最低期望。绝对没有评论应该解释编程语言的特性。例如var x: Int = 0 // declares a new mutable variable called x, to the Int value 0，学习 Swift 的教程除外。

以这种方式进行评论似乎很有帮助，因为您可能会争辩说它为初学者解释了一些事情。可能是这样，但对于所有其他读者来说，这令人窒息。想象一下，如果小说必须定义他们使用的所有英语单词。

相反，文档的目标是解释事物的目的和用途。要回答以下问题：

  • 为什么你以这种方式实现某些东西，而不是另一种方式？
  • 这种方法的目的是什么？
  • 我的委托的这个方法什么时候会被调用？

案例分析：Equatable

举个很好的例子，看看文档Equatable

需要注意的一些事项：

  1. 它是为 Swift 开发人员的受众编写的。它使用了许多它没有解释的东西，例如数组、字符串、常量、变量声明、赋值、if语句、方法调用（例如Array.contains(_:)）、字符串插值、print函数。
  2. 它解释了该协议的一般目的。
  3. 它解释了如何使用这个协议
  4. 它解释了如何采用此协议供自己使用

  5. 它记录了类型系统无法强制执行的合同要求。

    由于 Equatable 类型的实例之间的相等是一种等价关系，因此任何符合 Equatable 的自定义类型都必须满足三个条件，对于任何值a、b和c：

    • a == a总是正确的（反身性）
    • a == b意味着 b == a（对称）
    • a == b并b == c暗示a == c（及物性）

  6. 它解释了对协议的可能误解（“平等与身份分离”）

推荐阅读