[Go] 编码规范
gofmt
大部分的格式问题可以通过 gofmt 解决,gofmt 自动格式化代码,保证所有的Go代码与官方推荐的格式保持一致,于是所有格式有关问题,都以 gofmt 的结果为准。
注释
在编码阶段应该同步写好变量、函数、包的注释,最后可以利用 godoc 导出文档。注释必须是完整的句子,句子的结尾应该用句号作为结尾(英文句号)。注释推荐用英文,可以在写代码过程中锻炼英文的阅读和书写能力。而且用英文不会出现各种编码的问题。
每个包都应该有一个包注释,一个位于 package 子句之前的块注释或行注释。包如果有多个 go 文件,只需要出现在一个 go 文件中即可。
// ping包实现了常用的ping相关的函数 package ping
导出函数注释,第一条语句应该为一条概括语句,并且使用被声明的名字作为开头。
// Myfunction 求 a 和 b 的和,返回 sum。 func Myfunction(sum int) (a, b int) { }
命名
- 需要注释来补充的命名就不算是好命名。
- 使用可搜索的名称:单字母名称和数字常量很难从一大堆文字中搜索出来。单字母名称仅适用于短方法中的本地变量,名称长短应与其作用域相对应。若变量或常量可能在代码中多处使用,则应赋其以便于搜索的名称。
- 做有意义的区分:Product 和 ProductInfo 和 ProductData 没有区别,NameString 和 Name 没有区别,要区分名称,就要以读者能鉴别不同之处的方式来区分 。
- 函数命名规则:驼峰式命名,名字可以长但是得把功能,必要的参数描述清楚,函数名名应当是动词或动词短语,如 postPayment、deletePage、save。并依 Javabean 标准加上 get、set、is 前缀。例如:xxx + With + 需要的参数名 + And + 需要的参数名 + …..
- 结构体命名规则:结构体名应该是名词或名词短语,如 Custome、WikiPage、Account、AddressParser,避免使用 Manager、Processor、Data、Info 这样的类名,类名不应当是动词。
- 包名命名规则:包名应该为小写单词,不要使用下划线或者混合大小写。
- 接口命名规则:单个函数的接口名以“er”作为后缀,如 Reader,Writer。接口的实现则去掉“er”。
type Reader interface { Read(p []byte) (n int, err error) }
两个函数的接口名综合两个函数名
type WriteFlusher interface { Write([]byte) (int, error) Flush() error }
三个以上函数的接口名,抽象这个接口的功能,类似于结构体名
type Car interface { Start([]byte) Stop() error Recover() }
常量
常量均需使用全部大写字母组成,并使用下划线分词:
const APP_VER = "1.0"
如果是枚举类型的常量,需要先创建相应类型:
type Scheme string const ( HTTP Scheme = "http" HTTPS Scheme = "https" )
如果模块的功能较为复杂、常量名称容易混淆的情况下,为了更好地区分枚举类型,可以使用完整的前缀:
type PullRequestStatus int const ( PULL_REQUEST_STATUS_CONFLICT PullRequestStatus = iota PULL_REQUEST_STATUS_CHECKING PULL_REQUEST_STATUS_MERGEABLE )
变量
变量命名基本上遵循相应的英文表达或简写,在相对简单的环境(对象数量少、针对性强)中,可以将一些名称由完整单词简写为单个字母,例如:
- user 可以简写为 u
- userID 可以简写 uid
若变量类型为 bool 类型,则名称应以 Has, Is, Can 或 Allow 开头:
var isExist bool var hasConflict bool var canManage bool var allowGitHook bool
变量命名惯例
变量名称一般遵循驼峰法,但遇到特有名词时,需要遵循以下规则:
- 如果变量为私有,且特有名词为首个单词,则使用小写,如 apiClient
- 其它情况都应当使用该名词原有的写法,如 APIClient、repoID、UserID
- 错误示例:UrlArray,应该写成 urlArray 或者 URLArray
下面列举了一些常见的特有名词:
// A GonicMapper that contains a list of common initialisms taken from golang/lint var LintGonicMapper = GonicMapper{ "API": true, "ASCII": true, "CPU": true, "CSS": true, "DNS": true, "EOF": true, "GUID": true, "HTML": true, "HTTP": true, "HTTPS": true, "ID": true, "IP": true, "JSON": true, "LHS": true, "QPS": true, "RAM": true, "RHS": true, "RPC": true, "SLA": true, "SMTP": true, "SSH": true, "TLS": true, "TTL": true, "UI": true, "UID": true, "UUID": true, "URI": true, "URL": true, "UTF8": true, "VM": true, "XML": true, "XSRF": true, "XSS": true, }
struct 规范
struct 申明和初始化格式采用多行:
定义如下:
type User struct{ Username string Email string }
初始化如下:
u := User{ Username: "test", Email: "test@gmail.com", }
控制结构
if 接受初始化语句,约定如下方式建立局部变量
if err := file.Chmod(0664); err != nil { return err }
for 采用短声明建立局部变量
sum := 0 for i := 0; i < 10; i++ { sum += i }
return 尽早 return:一旦有错误发生,马上返回
f, err := os.Open(name) if err != nil { return err } d, err := f.Stat() if err != nil { f.Close() return err } codeUsing(f, d)
错误处理
- error作为函数的值返回,必须对error进行处理
- 错误描述如果是英文必须为小写,不需要标点结尾
- 采用独立的错误流进行处理
不要采用下面的处理错误写法
if err != nil { // error handling } else { // normal code }
采用下面的写法
if err != nil { // error handling return // or continue, etc. } // normal code
使用函数的返回值时,则采用下面的方式
x, err := f() if err != nil { // error handling return } // use x
panic
尽量不要使用panic,除非你知道你在做什么
import
对 import 的包进行分组管理,用换行符分割,而且标准库作为分组的第一组。如果你的包引入了三种类型的包,标准库包,程序内部包,第三方包,建议采用如下方式进行组织你的包
package main import ( "fmt" "os" "kmg/a" "kmg/b" "code.google.com/a" "github.com/b" )
在项目中不要使用相对路径引入包:
// 错误示例 import “../net” // 正确的做法 import “github.com/repo/proj/src/net”
goimports 会自动帮你格式化
参数传递
- 对于少量数据,不要传递指针
- 对于大量数据的 struct 可以考虑使用指针
- 传入参数是 map,slice,chan 不要传递指针,因为 map,slice,chan 是引用类型,不需要传递指针的指针
单元测试
单元测试文件名命名规范为 example_test.go
测试用例的函数名称必须以 Test 开头,例如:TestExample
参考:
http://blog.csdn.net/myzlhh/article/details/52269591
https://golang.org/doc/effective_go.html#commentary
Java Web 项目结构
Java se 与 Java web项目目录结构(最后为应用SSH框架目录结构)
Java 后台开发中model与entity(实体类)的区别
Java Web中的Action、Dao、Service、Model学习笔记
深入浅出Java MVC(Model View Controller) ---- (JSP + servlet + javabean实例)