EffectiveGo-1-格式化、注释、命名、分号

Parts of Effective Go

格式化

gofmt或者go fmt命令将Go程序按照标准风格缩进、对齐,保留注释并在需要时重新格式化

注释

Go支持C风格的块注释/* */C++风格的行注释//
godoc既是一个程序,又是一个Web服务器,它对Go的源码进行处理,并提取包中的文档内容
例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
/*
godoc 会提取在源码中
顶级声明(package xx)之前(包括顶级声明本身)的全部内容
作为说明文档

注意:这段文字的注释 与 顶级声明(package xx) 之间不应该出现空行

这段文字无需注意格式
godoc 会类型 gofmt 一样处理这段文字

如果较为简单的包,也可以使用
// xxx
// xxxxxxx
package xx

在包中,任何顶级声明之前的注释都会被当成文档
在程序中,每个可导出的名称(大写字母开头)之前都应该有文档注释
例:
// Add two int Return Sum
func Add(x, y int) (sum int) {
sum = x + y
return
}
*/
package xx

命名

包名

1
2
3
4
5
// 当一个包被导入后,包名就会变成内容的访问器
import "bytes"

// 被导入的包就能通过包名来引用
bytes.Buffer

包名应为其源码目录的基本名称
例:在src/pkg/encoding/base64中的包应作为encoding/base64导入,其包名应该是base64,而不是encoding_base64或者encodingBase64
长命名并不会使其更具可读性
例:once.Do, once.Do(setup)表述足够清晰,使用once.DoOrWaitUntilDone(step)并不好

获取器

Go并不对获取器getter和设置器setter提供自动支持
例:若有一个名为owner的字段(小写-未导出),其获取器应该命名为Owner(大写-导出)而不是命名为GetOwner,设置器可命名为SetOwner

1
2
3
4
owner := obj.Owner()
if owner != nil {
obj.SetOwner(user)
}

接口名

按照约定,只包含一个方法的接口应当以该方法名加上-er后缀来命名
例:ReaderWriterFormatterCloseNotifier
请将字符转换方法命名为String而不是ToString

驼峰命名法

Go约定使用驼峰命名法 MixedCaps 或者 mixedCaps

分号

C一样,Go也是使用分号来结束语句,只不过这个分号不用出现在源代码里,词法分析器lexer会依据规则自动在源码中插入分号。

插入规则

if the newline comes after a token that could end a statement, insert a semicolon
若在新行前的最后一个标记为标识符(int\float64...)数值字符串常量breakcontinuefallthroughreturn++--)})之一,则始终在该标记后插入分号。

如果在一行中写多个语句,需要用分号隔开

无论如何,都不能将一个控制结构(ifforswitchselect)的左大括号放在下一行

1
2
3
4
5
6
7
8
9
10
// 正确写法
if x < f() {
do()
}

// 错误写法
if x < f() // ; 这个地方会被插入一个分号
{
do()
}