Xcode 中循环变量的文档注释
Documentation comment for loop variable in 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 {
// ...
}
背景：
我不使用 "good" 变量名的原因是我正在实现一个使用数学符号导出的数值算法。在这种情况下，它只有单字母变量名。为了更好地看到推导和实现之间的联系，我使用了相同的变量名。
现在我想对代码中的变量进行注释。
/// 的使用主要是为了在 Swift 中记录 class、结构等的 API。
因此，如果在 class、func、class/struct 中的 var/let 等之前使用，您将向其附加文档Xcode 了解如何显示内联的代码方面。它不知道如何为函数内部的事物获取该信息，因为此时这不是 /// 的意图（它可能适用于简单的 var/let 但不太可能完全是故意的）。
改为使用简单的 // 代码注释，以使任何在代码中工作的人受益，但要避免过度记录代码，因为好的代码很可能会向精通该语言的任何人自我解释并添加不需要的文档会妨碍阅读代码。
这是目前Swift中代码文档的一个很好的参考Swift Documentation
如果我在 PR 中看到这样的事情，我会强烈反对。 i 是一个被广泛采用的 "term of art" for 循环索引。一般来说，如果你的变量声明名需要注释，你需要一个更好的变量名。有一些例外，例如当它存储复杂的数据时 uses/invariants 无法在类型系统中以更好的方式捕获。
我认为评论是初学者容易犯的错误之一，主要是被老师误导，或者还没有完全理解评论的目的。不存在创建基于英语的 psuedo-programming 语言的评论，您的整个应用程序将被复制。理解编程语言是对项目贡献者的最低期望。绝对没有评论应该解释编程语言的特性。例如。 var x: Int = 0 // declares a new mutable variable called x, to the Int value 0，学习教程除外 Swift。
以这种方式评论似乎很有帮助，因为您可能会争辩说它为初学者解释了一些事情。情况可能是这样，但它让所有其他读者感到窒息。想象一下，如果小说必须定义他们使用的所有英文单词。
相反，文档的目标是解释事物的用途和用途。回答这样的问题：
- 为什么你用这种方式而不是其他方式来实现？
- 这个方法有什么作用？
- 我的委托的这个方法什么时候被调用？
案例研究：Equatable
举个好例子，看看 documentation of Equatable
一些注意事项：
- 它是为 Swift 开发人员的读者而写的。它使用了许多它没有解释的东西，例如数组、字符串、常量、变量声明、赋值、
if 语句、方法调用（例如 Array.contains(_:)）、字符串插值、print函数。
- 它解释了这个协议的一般目的。
- 它解释了如何使用这个协议
- 它解释了如何采用此协议供您自己使用
它记录了类型系统无法强制执行的合同要求。
Since equality between instances of Equatable types is an equivalence relation, any of your custom types that conform to Equatable must satisfy three conditions, for any values a, b, and c:
a == a is always true (Reflexivity) a == b implies b == a (Symmetry)a == b and b == c implies a == c (Transitivity)
它解释了对协议的可能误解 ("Equality is Separate From Identity")
我知道我们可以使用
/// 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 {
// ...
}
背景：
我不使用 "good" 变量名的原因是我正在实现一个使用数学符号导出的数值算法。在这种情况下，它只有单字母变量名。为了更好地看到推导和实现之间的联系，我使用了相同的变量名。
现在我想对代码中的变量进行注释。
/// 的使用主要是为了在 Swift 中记录 class、结构等的 API。
因此，如果在 class、func、class/struct 中的 var/let 等之前使用，您将向其附加文档Xcode 了解如何显示内联的代码方面。它不知道如何为函数内部的事物获取该信息，因为此时这不是 /// 的意图（它可能适用于简单的 var/let 但不太可能完全是故意的）。
改为使用简单的 // 代码注释，以使任何在代码中工作的人受益，但要避免过度记录代码，因为好的代码很可能会向精通该语言的任何人自我解释并添加不需要的文档会妨碍阅读代码。
这是目前Swift中代码文档的一个很好的参考Swift Documentation
如果我在 PR 中看到这样的事情，我会强烈反对。 i 是一个被广泛采用的 "term of art" for 循环索引。一般来说，如果你的变量声明名需要注释，你需要一个更好的变量名。有一些例外，例如当它存储复杂的数据时 uses/invariants 无法在类型系统中以更好的方式捕获。
我认为评论是初学者容易犯的错误之一，主要是被老师误导，或者还没有完全理解评论的目的。不存在创建基于英语的 psuedo-programming 语言的评论，您的整个应用程序将被复制。理解编程语言是对项目贡献者的最低期望。绝对没有评论应该解释编程语言的特性。例如。 var x: Int = 0 // declares a new mutable variable called x, to the Int value 0，学习教程除外 Swift。
以这种方式评论似乎很有帮助，因为您可能会争辩说它为初学者解释了一些事情。情况可能是这样，但它让所有其他读者感到窒息。想象一下，如果小说必须定义他们使用的所有英文单词。
相反，文档的目标是解释事物的用途和用途。回答这样的问题：
- 为什么你用这种方式而不是其他方式来实现？
- 这个方法有什么作用？
- 我的委托的这个方法什么时候被调用？
案例研究：Equatable
举个好例子，看看 documentation of Equatable
一些注意事项：
- 它是为 Swift 开发人员的读者而写的。它使用了许多它没有解释的东西，例如数组、字符串、常量、变量声明、赋值、
if语句、方法调用（例如Array.contains(_:)）、字符串插值、print函数。 - 它解释了这个协议的一般目的。
- 它解释了如何使用这个协议
- 它解释了如何采用此协议供您自己使用
它记录了类型系统无法强制执行的合同要求。
Since equality between instances of Equatable types is an equivalence relation, any of your custom types that conform to Equatable must satisfy three conditions, for any values
a,b, andc:a == ais always true (Reflexivity)a == bimplies b == a (Symmetry)a == bandb == cimpliesa == c(Transitivity)
它解释了对协议的可能误解 ("Equality is Separate From Identity")