案例研究：`Equatable`

Question

我知道我们可以使用

/// 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 {
    // ...
}

背景：

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

现在，我想对代码中的变量进行注释。

Answer 1

使用///主要用于记录Swift中的类，结构等的API。

因此，如果在类/结构等中的class，func，var / let等之前使用，您会将文档附加到Xcode的那个代码方面了解如何显示内联。它不知道如何为函数内部的事物获取该信息，因为这不是///的意图（它可能适用于简单的var / let，但不可能完全出于目的）。

对于使用该代码的人员，请使用简单的//代码注释，但请避免过多地编写代码，因为好的代码很可能会自我解释给精通该语言的任何人，并且可以添加不需要的文档只是阅读代码。

这是目前Swift Documentation

中Swift代码文档的很好参考

Answer 2

如果我在PR中看到它，我会大力推销类似的东西。 i是循环索引广泛采用的“技术术语”。通常，如果需要对变量声明名称进行注释，则需要更好的变量名称。有一些例外，例如当它存储具有复杂用途/不变式的数据时，在类型系统中无法更好地捕获这种数据。

我认为评论是初学者会犯错的一个领域，主要是因为被老师误导或尚未完全理解评论的目的。不存在创建基于英语的伪编程语言的注释，因此不会复制您的整个应用程序。对项目贡献者的最低期望是了解编程语言。绝对没有评论可以解释编程语言的功能。例如。 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(_:)），字符串插值，{{1 }}功能。
它解释了此协议的一般目的。
它说明了如何使用此协议
它说明了如何采用此协议供自己使用
它记录了类型系统无法强制执行的合同要求。
由于Equatable类型的实例之间的相等性是等效关系，因此，符合Equatable的任何自定义类型必须满足三个条件，即任何值print，a和b ：
- c始终为真（自反性）
- a == a意味着b == a（对称）
- a == b和a == b表示b == c（传递性）
它解释了关于协议的可能误解（“平等与身份是分开的”）

Xcode

2 个答案:

案例研究：Equatable

案例研究：`Equatable`