Warm tip: This article is reproduced from serverfault.com, please click

go-出于文档目的输入别名

(go - Type aliases for documentation purposes)

发布于 2020-11-28 14:40:00

使用类型别名使go代码更具自记录性是否被认为是一种好习惯?一个例子:

type User struct {
    // user stuff
}

type Username = string

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

很明显,Foo从用户名映射到用户结构,而无需解释注释中的任何内容,如果类型定义为,则可能需要map[string]User使用此方法吗?

函数参数就像局部变量一样,但是它们也可以作为文档。

如果类型是描述性的,则应简短:

func AfterFunc(d持续时间,f func())*计时器

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

如果类型比较不明确,则这些名称可能会提供说明文件:

func Unix(sec,nsec int64)时间

func HasPrefix(s,前缀[] byte)布尔

引用自https://talks.golang.org/2014/names.slide#9使类型减少歧义似乎是一个值得追求的目标。time.Duration只是简单的type Duration int64,它不是别名,但是纯粹从文档的角度来看,我认为效果是相似的。

Questioner
user2133814
Viewed
0
Flimzy 2020-11-29 00:55:36

我犹豫要回答,因为这最终是一个自以为是的问题。但是我避免这种情况的原因是:

  1. 它不是很明显,因此可以说违反了“最小惊讶原则”如果我在某些Go代码中遇到了这种情况,我会认为这是一个错误,或者是迁移造成的混乱,我会尝试将其删除。
  2. 即使从表面上看,文档的价值充其量也是充其量。map[string]User应该将用户名映射到用户的上下文中应该很清楚如果你有多个相似的映射,例如,一个映射用户名,一个映射用户ID,则变量名应消除歧义。如果不是,则类型别名也可能不够。你需要一些清晰的文档。
  3. 最后,静态分析工具(例如内置在许多IDE中的工具)会将类型别名解析为其规范类型,这意味着任何可感知的文档价值都将受到限制。