用于文档目的的类型别名 [关闭]答案

【问题标题】：Type aliases for documentation purposes [closed]用于文档目的的类型别名 [关闭]
【发布时间】：2020-11-28 14:40:00
【问题描述】：

使用类型别名来使 Go 代码更具自我记录性是否被认为是一种好习惯？一个例子：

type User struct {
    // user stuff
}

type Username = string

func Foo(users map[Username]User){
    // do stuff
}

很明显，Foo 需要一个从用户名到用户结构的映射，而不需要在 cmets 中解释任何内容，如果类型定义为 map[string]User，则可能需要这种方法。这种方法有什么负面影响吗？

函数参数类似于局部变量，但它们也用作文档。

类型是描述性的，它们应该是简短的：

func AfterFunc(d Duration, f func()) *Timer

func Escape(w io.Writer, s []byte)

类型比较模糊的地方，这些名称可能会提供文档：

func Unix(sec, nsec int64) 时间

func HasPrefix(s, prefix []byte) bool

引自https://talks.golang.org/2014/names.slide#9。使类型不那么模棱两可似乎是一个有价值的目标。 time.Duration 就是简单的type Duration int64，不是别名，只是单纯从文档的角度来说我觉得效果差不多。

【问题讨论】：

它不会比评论// Username 提供更多的好处，这也不会被认为很有帮助。为您的地图声明一个实际类型并记录下来会更容易接受。
@JimB 之类的 type Users map[string]User 带有有用的文档字符串？我同意我的示例中的名称不是很好，但这在某种程度上是提出最简单示例的副作用。
函数声明的读者必须了解Username是什么才能理解函数。说明用户是由用户名键入的地图的功能文档注释更好。一切都包含在为函数显示的文档中。

标签： go type-alias

【解决方案1】：

我不愿回答，因为这最终是一个固执己见的问题。但我会避免这种情况的原因是：

这是非常不明显的，因此可以说违反了Principle of Least Astonishment。如果我在一些 Go 代码中遇到了这个问题，我会认为这是一个错误，或者是迁移过程中出现的问题，我会尝试将其删除。
即使从表面上看，文档价值也最多是可疑的。从上下文中应该很清楚map[string]User 应该将用户名映射到用户。例如，如果您有多个相似的映射，一个映射用户名，一个映射用户 ID，例如，变量的名称应该消除歧义。如果没有，类型别名可能也不够用。您需要一些清晰的文档。
最后，静态分析工具（例如许多 IDE 中内置的工具）会将类型别名解析为其规范类型，这意味着任何感知到的文档价值无论如何都会受到限制。

【讨论】：

你对普通的 def type Username string 也这么说吗？
@mh-cbon：并非所有要点都适用于标准类型定义。你问的是哪一个？不过，一般来说，我更喜欢为功能保留类型定义，而不是文档。我发现在命名类型和基本类型之间不断地来回进行类型转换很麻烦，除非我在类型中内置了功能，否则我更愿意避免这种情况。
I find constantly type converting back and forth between a named type and a base type to be cumbersome, and prefer to avoid it except when I have functionality built into a type. 这是我同意的一个很好的理由。我提出了这一点，以防 OP 对各种类型定义感到困惑。
关于在命名类型和基本类型之间转换的问题不适用于类型别名，因为类型别名实际上并不创建类型，所以在我的示例中可以使用纯字符串，对吗？这实际上是我从使用类型别名中感受到的一个好处。
@user2133814：对，转换不适用于别名。

【解决方案2】：

别名声明无论如何都不会创建一个不同于创建它的类型的新的不同类型。它只是为 T2 表示的类型引入了一个别名 T1，一种替代拼写。

类型别名不适合日常使用。引入它们是为了支持逐步代码修复，同时在大规模重构期间在包之间移动类型。代码库重构（在 Go 的帮助下）详细介绍了这一点。

查看此proposal 了解更多信息

【讨论】：

我了解它们是什么以及为什么创建它们。你能找到任何不适合日常使用的参考吗？

【解决方案3】：

使用类型别名来使 Go 代码更具自我记录性是否被认为是一种好习惯？

不，一点也不。

类型别名是一种表达类型关系的技术方法，在大规模重构等特殊情况下无法实现。

在文档中滥用类型别名是 100% 不行的。

【讨论】：

有什么负面影响？我了解类型别名的初衷，但没有找到任何权威的使用它们作为文档的东西。这是一个很好的迹象，表明它不是被广泛认为是好的做法，但我想知道为什么，因为它似乎遵循一些围棋咒语，比如清晰。
@user2133814 这不是正确的文档和滥用。