问题

• 整体混乱，但功能齐全，是未来的起点。*

— 提交 891b12dc
目前，gophers 包使用起来困难且难以修改。要开始使用它并不容易：

// (no documentation)
func GetPerson(id string) *Person

我多次使用和修改过它，每次都需要阅读其内部代码来弄清楚：

• "id" 可以是什么样的值？
• 它的确切格式是什么？
• 对于 GH 用户名，前导 '@' 是必需的吗？可选的？不需要的？
• 它是区分大小写的还是不区分大小写的？
• 在添加到 addPerson(...) 行时，应该以什么顺序/哪种类型的信息？

尽管是一个内部包，gophers 是一个重要的包，为其他四个包提供价值，并可能在更多地方被使用。它不再只是用于计算统计数据，还用于跟踪包所有者和分配审查。作为内部包意味着我们可以轻松地(甚至在需要时破坏 API)更改它(如果我们就改进设计达成一致意见)。

提议的解决方案

我认为可以通过以下方式使其更容易使用：

• 对其进行文档化(这样它的 godoc 就是您使用它所需的全部内容，无需阅读代码)

例如：

// GetPerson looks up a person by id and returns one if found, or nil otherwise.
//
// The id is case insensitive, and may be one of:
// 	- full name ("Brad Fitzpatrick")
// 	- GitHub username ("@bradfitz")
// 	- Gerrit <account ID>@<instance ID> ("5065@62eb7196-b449-3ce5-99f1-c037f21e1705")
// 	- email ("bradfitz@golang.org")
func GetPerson(id string) *Person

@bradfitz 如果您不希望被用作示例，请告诉我，我们可以使用其他人(我很乐意自愿)或使用通用名称。但我认为一个知名的真实用户会成为一个更好的示例。
通过使其内部 addPerson 逻辑更加明确而不是隐式来使其更易于修改：
例如，现在的情况是：

addPerson("Filippo Valsorda", "", "6195@62eb7196-b449-3ce5-99f1-c037f21e1705")
addPerson("Filippo Valsorda", "filippo@cloudflare.com")
addPerson("Filippo Valsorda", "filippo@golang.org", "11715@62eb7196-b449-3ce5-99f1-c037f21e1705")
addPerson("Filippo Valsorda", "filippo@golang.org", "hi@filippo.io", "@FiloSottile")

// what kind of changes should be done to modify the end result Person struct?

它可以是更明确的东西，沿着如下所示的路线：

add(Person{
	Name:      "Filippo Valsorda",
	GitHub:    "FiloSottile",
	Gerrit:    "filippo@golang.org",
	GerritIDs: []int{6195, 11715}, // Gerrit account IDs.
	GitEmails: []string{
		"filippo@golang.org",
		"filippo@cloudflare.com",
		"hi@filippo.io",
	},
	gomote: "valsorda", // Gomote user.
})

其意图是使人们能够手动添加和修改他们的条目，具有可预测的结果，同时仍然能够使用代码生成(类似于 gopherstats -mode=find-gerrit-gophers )来添加缺失的条目。
这只是一个快速草稿提案，不一定是最终的 API 设计。如果总体方向受到欢迎，但仍有担忧或改进建议，我很高兴能充实它并纳入反馈。在拥有坚实的设计之前，我不会发送 CL。
/cc @bradfitz@andybons