一 : 命名规范

命名是代码规范中很重要的一部分，统一的命名规则有利于提高的代码的可读性，好的命名仅仅通过命名就可以获取到足够多的信息。

Go在命名时以字母a到Z或a到Z或下划线开头，后面跟着零或更多的字母、下划线和数字(0到9)。

Go不允许在命名时中使用@、$和%等标点符号。

Go是一种区分大小写的编程语言。因此，Manpower和manpower是两个不同的命名。

  • 当命名（包括常量、变量、类型、函数名、结构字段等等）以一个大写字母开头，如：Group1，那么使用这种形式的标识符的对象就可以被外部包的代码所使用（客户端程序需要先导入这个包），这被称为导出（像面向对象语言中的 public）；

  • 命名如果以小写字母开头，则对包外是不可见的，但是他们在整个包的内部是可见并且可用的（像面向对象语言中的 private ）

  1. 包命名：package

保持package的名字和目录保持一致，尽量采取有意义的包名，简短，有意义，尽量和标准库不要冲突。包名应该为小写单词，不要使用下划线或者混合大小写。

package demo

package main

  1. 文件命名

尽量采取有意义的文件名，简短，有意义，应该为小写单词，使用下划线分隔各个单词。

test.go

  1. 结构体命名

  • 采用驼峰命名法，首字母根据大写或者小写

  • struct 申明和初始化格式采用多行，例如下面：

// 多行申明
type User struct{
    Username  string
    Email     string
}

// 多行初始化
u := User{
    Username: "admin",
    Email:    "admin@admin.com",
}

  1. 接口命名

  • 命名规则基本和上面的结构体类型相似

  • 单个函数的结构名以 “er” 作为后缀，例如 Reader , Writer 。

type Reader interface {
    Read(p []byte) (n int, err error)
}

  1. 变量命名

  • 和结构体类似，变量名称一般遵循驼峰法，首字母根据访问控制原则大写或者小写，但遇到特有名词时，需要遵循以下规则：

    • 如果变量为私有，且特有名词为首个单词，则使用小写，如 apiClient

    • 其它情况都应当使用该名词原有的写法，如 APIClient、repoID、UserID

    • 错误示例：UrlArray，应该写成 urlArray 或者 URLArray

  • 若变量类型为 bool 类型，则名称应以 Has, Is, Can 或 Allow 开头

var isExist bool
var hasConflict bool
var canManage bool
var allowGitHook bool

  1. 常量命名

常量均需使用全部大写字母组成，并使用下划线分词

const APP_VER = "1.0"

  1. 关键字

保留关键字不能用作常量或变量或任何其他标识符名称。

二 注释

Go提供C风格的/* */块注释和C ++风格的//行注释。行注释是常态；块注释主要显示为包注释，但在表达式中很有用或禁用大量代码。

  • 单行注释是最常见的注释形式，你可以在任何地方使用以 // 开头的单行注释

  • 多行注释也叫块注释，均已以 /* 开头，并以 */ 结尾，且不可以嵌套使用，多行注释一般用于包的文档描述或注释成块的代码片段

go 语言自带的 godoc 工具可以根据注释生成文档，生成可以自动生成对应的网站（ golang.org 就是使用 godoc 工具直接生成的），注释的质量决定了生成的文档的质量。每个包都应该有一个包注释，在package子句之前有一个块注释。对于多文件包，包注释只需要存在于一个文件中，任何一个都可以。包评论应该介绍包，并提供与整个包相关的信息。它将首先出现在godoc页面上，并应设置下面的详细文档。

  1. 包注释

每个包都应该有一个包注释，一个位于package子句之前的块注释或行注释。包如果有多个go文件，只需要出现在一个go文件中（一般是和包同名的文件）即可。 包注释应该包含下面基本信息(请严格按照这个顺序，简介，创建人，创建时间）：

  • 包的基本简介（包名，简介）

  • 创建者，格式： 创建人： rtx 名

  • 创建时间，格式：创建时间： yyyyMMdd

例如 util 包的注释示例如下:

// util 包， 该包包含了项目共用的一些常量，封装了项目中一些共用函数。
// 创建人： admin
// 创建时间： 20200606

  1. 结构（接口）注释

每个自定义的结构体或者接口都应该有注释说明，该注释对结构进行简要介绍，放在结构体定义的前一行，格式为： 结构体名， 结构体说明。

同时结构体内的每个成员变量都要有说明，该说明放在成员变量的后面（注意对齐)

// User ， 用户对象，定义了用户的基础信息
type User struct{
    Username  string // 用户名
    Email     string // 邮箱
}

  1. 函数（方法）注释

每个函数，或者方法（结构体或者接口下的函数称为方法）都应该有注释说明，函数的注释应该包括三个方面（严格按照此顺序撰写）：

  • 简要说明，格式说明：以函数名开头，“，”分隔说明部分

  • 参数列表：每行一个参数，参数名开头，“，”分隔说明部分

  • 返回值： 每行一个返回值

// NewtAttrModel ， 属性数据层操作类的工厂方法
// 参数：
//      ctx ： 上下文信息
// 返回值：
//      属性操作类指针
func NewAttrModel(ctx *common.Context) *AttrModel {

}

  1. 代码逻辑注释

对于一些关键位置的代码逻辑，或者局部较为复杂的逻辑，需要有相应的逻辑说明，方便其他开发者.

// 从 Redis 中批量读取属性，对于没有读取到的 id ， 记录到一个数组里面，准备从 DB 中读取

  1. 注释风格

统一使用中文注释，对于中英文字符之间严格使用空格分隔， 这个不仅仅是中文和英文之间，英文和中文标点之间也都要使用空格分隔.

  • 建议全部使用单行注释

  • 和代码的规范一样，单行注释不要过长，禁止超过 120 字符。

    6. 包的分类

    import 在多⾏的情况下，goimports 会⾃动帮你格式化，但是我们这⾥还是规范⼀下 import 的⼀些规范，如果你在⼀个⽂件⾥⾯引⼊了⼀个 package，还是建议采⽤如下格式：

    import (
    "fmt"
)

    如果你的包引⼊了三种类型的包:

    1. go语言自带的包

    2. Go get安装的 第三方包

    3. 程序内部的包(自己写的包)

    建议使用如下方式组织你的包:

    import (

    "encoding/json" 
    "strings"

    "myproject/models" 
    "myproject/controller" 
    "myproject/utils"

    "github.com/astaxie/beego" 
    "github.com/go-sql-driver/mysql"

)

    每类的包使用空行隔开,引入包要使用完整路径,但是如果引入本项目中的其他包,最好使用相对路径.

    7.错误处理

    • 错误处理的原则就是不能丢弃任何有返回 err 的调⽤，不要使⽤ _ 丢弃，必须全部处理。接收到错误，要么返回 err，或者使⽤ log 记录下来

    • 尽早 return：⼀旦有错误发⽣，⻢上返回

    • 尽量不要使⽤ panic，除⾮你知道你在做什么

    • 错误描述如果是英⽂必须为⼩写，不需要标点结尾

    • 采⽤独⽴的错误流进⾏处理

    if err != nil {

} else {

}

if err != nil {

return

}