golang语言编码规范的实现

本规范旨在为日常Go项目开发提供一个代码的规范指导,方便团队形成一个统一的代码风格,提高代码的可读性,规范性和统一性。本规范将从命名规范,注释规范,代码风格和 Go 语言提供的常用的工具这几个方面做一个说明。该规范参考了 go 语言官方代码的风格制定。

一、 命名规范

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

Go在命名时以字母a到Z或a到Z或下划线开头,后面跟着零或更多的字母、下划线和数字(0到9)。Go不允许在命名时中使用@、$和%等标点符号。Go是一种区分大小写的编程语言。因此,Manpower和manpower是两个不同的命名。

当命名(包括常量、变量、类型、函数名、结构字段等等)以一个大写字母开头,如:Group1,那么使用这种形式的标识符的对象就可以被外部包的代码所使用(客户端程序需要先导入这个包),这被称为导出(像面向对象语言中的 public);
命名如果以小写字母开头,则对包外是不可见的,但是他们在整个包的内部是可见并且可用的(像面向对象语言中的 private )

1、包命名:package

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

package demo
package main

2、 文件命名

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

my_test.go

3、 结构体命名

采用驼峰命名法,首字母根据访问控制大写或者小写
struct 申明和初始化格式采用多行,例如下面:

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

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

4、 接口命名

命名规则基本和上面的结构体类型
单个函数的结构名以 “er” 作为后缀,例如 Reader , Writer 。

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

5、变量命名

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

  • 如果变量为私有,且特有名词为首个单词,则使用小写,如 apiClient
  • 其它情况都应当使用该名词原有的写法,如 APIClient、repoID、UserID
  • 错误示例:UrlArray,应该写成 urlArray 或者 URLArray

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

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

6、常量命名

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

const APP_VER = "1.0"

如果是枚举类型的常量,需要先创建相应类型:

type Scheme string

const (
  HTTP Scheme = "http"
  HTTPS Scheme = "https"
)

7、 关键字

下面的列表显示了Go中的保留字。这些保留字不能用作常量或变量或任何其他标识符名称。

二、注释

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

  • 单行注释是最常见的注释形式,你可以在任何地方使用以 // 开头的单行注释
  • 多行注释也叫块注释,均已以 /* 开头,并以 */ 结尾,且不可以嵌套使用,多行注释一般用于包的文档描述或注释成块的代码片段

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

详细的如何写注释可以
参考:http://golang.org/doc/effective_go.html#commentary

1、包注释

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

  • 包的基本简介(包名,简介)
  • 创建者,格式: 创建人: rtx 名
  • 创建时间,格式:创建时间: yyyyMMdd

例如 util 包的注释示例如下

// util 包, 该包包含了项目共用的一些常量,封装了项目中一些共用函数。
// 创建人: hanru
// 创建时间: 20190419

2、结构(接口)注释

每个自定义的结构体或者接口都应该有注释说明,该注释对结构进行简要介绍,放在结构体定义的前一行,格式为: 结构体名, 结构体说明。同时结构体内的每个成员变量都要有说明,该说明放在成员变量的后面(注意对齐),实例如下:

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

3、函数(方法)注释

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

  • 简要说明,格式说明:以函数名开头,“,”分隔说明部分
  • 参数列表:每行一个参数,参数名开头,“,”分隔说明部分
  • 返回值: 每行一个返回值

示例如下:

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

4、代码逻辑注释

对于一些关键位置的代码逻辑,或者局部较为复杂的逻辑,需要有相应的逻辑说明,方便其他开发者阅读该段代码,实例如下:

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

5、注释风格

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

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

上面 Redis 、 id 、 DB 和其他中文字符之间都是用了空格分隔。

  • 建议全部使用单行注释
  • 和代码的规范一样,单行注释不要过长,禁止超过 120 字符。

三、代码风格

1、缩进和折行

  • 缩进直接使用 gofmt 工具格式化即可(gofmt 是使用 tab 缩进的);
  • 折行方面,一行最长不超过120个字符,超过的请使用换行展示,尽量保持格式优雅。

我们使用Goland开发工具,可以直接使用快捷键:ctrl+alt+L,即可。

2、语句的结尾

Go语言中是不需要类似于Java需要冒号结尾,默认一行就是一条数据

如果你打算将多个语句写在同一行,它们则必须使用 ;

3、括号和空格

括号和空格方面,也可以直接使用 gofmt 工具格式化(go 会强制左大括号不换行,换行会报语法错误),所有的运算符和操作数之间要留空格。

// 正确的方式
if a > 0 {

} 

// 错误的方式
if a>0 // a ,0 和 > 之间应该空格
{    // 左大括号不可以换行,会报语法错误

}

4、import 规范
import在多行的情况下,goimports会自动帮你格式化,但是我们这里还是规范一下import的一些规范,如果你在一个文件里面

引入了一个package,还是建议采用如下格式:

import (
  "fmt"
)

如果你的包引入了三种类型的包,标准库包,程序内部包,第三方包,建议采用如下方式进行组织你的包:

import (
  "encoding/json"
  "strings"

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

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

有顺序的引入包,不同的类型采用空格分离,第一种实标准库,第二是项目包,第三是第三方包。

在项目中不要使用相对路径引入包:

// 这是不好的导入
import “../net”

// 这是正确的做法
import “github.com/repo/proj/src/net”

但是如果是引入本项目中的其他包,最好使用相对路径。

5、错误处理

错误处理的原则就是不能丢弃任何有返回err的调用,不要使用 _ 丢弃,必须全部处理。接收到错误,要么返回err,或者使用log记录下来
尽早return:一旦有错误发生,马上返回
尽量不要使用panic,除非你知道你在做什么
错误描述如果是英文必须为小写,不需要标点结尾
采用独立的错误流进行处理

// 错误写法
if err != nil {
  // error handling
} else {
  // normal code
}

// 正确写法
if err != nil {
  // error handling
  return // or continue, etc.
}
// normal code

6、测试

单元测试文件名命名规范为 example_test.go
测试用例的函数名称必须以 Test 开头,例如:TestExample
每个重要的函数都要首先编写测试用例,测试用例和正规代码一起提交方便进行回归测试

四、常用工具

上面提到了很过规范, go 语言本身在代码规范性这方面也做了很多努力,很多限制都是强制语法要求,例如左大括号不换行,引用的包或者定义的变量不使用会报错,此外 go 还是提供了很多好用的工具帮助我们进行代码的规范,

gofmt
大部分的格式问题可以通过gofmt解决, gofmt 自动格式化代码,保证所有的 go 代码与官方推荐的格式保持一致,于是所有格式有关问题,都以 gofmt 的结果为准。

goimport
我们强烈建议使用 goimport ,该工具在 gofmt 的基础上增加了自动删除和引入包.

go get golang.org/x/tools/cmd/goimports

go vet
vet工具可以帮我们静态分析我们的源码存在的各种问题,例如多余的代码,提前return的逻辑,struct的tag是否符合标准等。

go get golang.org/x/tools/cmd/vet

使用如下:

go vet .

到此这篇关于golang语言编码规范的实现的文章就介绍到这了,更多相关golang语言编码规范内容请搜索我们以前的文章或继续浏览下面的相关文章希望大家以后多多支持我们!

(0)

相关推荐

  • Python 常用 PEP8 编码规范详解

    Python 常用 PEP8 编码规范 代码布局 缩进 每级缩进用4个空格. 括号中使用垂直隐式缩进或使用悬挂缩进. EXAMPLE: # (垂直隐式缩进)对准左括号 foo = long_function_name(var_one, var_two, var_three, var_four) # (悬挂缩进) 一般情况只需多一层缩进 foo = long_function_name( var_one, var_two, var_three, var_four) # (悬挂缩进) 但下面情况,

  • python 编码规范整理

    一 代码编排 1 缩进4个空格的缩进(编辑器都可以完成此功能),不要使用Tap,更不能混合使用Tap和空格. 2 每行最大长度79,换行可以使用反斜杠,最好使用圆括号.换行点要在操作符的后边敲回车. 3 类和top-level函数定义之间空两行:类中的方法定义之间空一行:函数内逻辑无关段落之间空一行:其他地方尽量不要再空行. 二 文档编排 1 模块内容的顺序:模块说明和docstring-import-globals&constants-其他定义.其中import部分,又按标准.三方和自己编写顺

  • 最全的Javascript编码规范(推荐)

    1.嵌入规则 Javascript程序应该尽量放在.js的文件中,需要调用的时候在页面中以<script src="filename.js">的形式包含进来.Javascript代码若不是该页面专用的,则应尽量避免在页面中直接编写Javascript代码. 2.对齐缩进与换行 a) 缩进 在同一系统中应采用同一种缩进标准,本文提倡缩进大小为4个空格.各编译器对Tab键所代替的空白大小定义不同.建议在设置开发环境时,将编辑器里的Tab快捷键重新设置成4个空格.多数编译器提供了

  • Python 编码规范(Google Python Style Guide)

    Python 风格规范(Google) 本项目并非 Google 官方项目, 而是由国内程序员凭热情创建和维护. 如果你关注的是 Google 官方英文版, 请移步 Google Style Guide 以下代码中 Yes 表示推荐,No 表示不推荐. 分号 不要在行尾加分号, 也不要用分号将两条命令放在同一行. 行长度 每行不超过80个字符 以下情况除外: 长的导入模块语句 注释里的URL 不要使用反斜杠连接行. Python会将 圆括号, 中括号和花括号中的行隐式的连接起来 , 你可以利用这

  • Node.js编码规范

    调用函数的时候,函数名与左括号之间没有空格. 函数名与参数序列之间,没有空格:所有其他语法元素与左括号之间,都有一个空格. 使用小驼峰式命名法作为所有变量和属性的命名规则. 缩进使用两空格,统一使用单引号. 关联数组,除非键名中有空格或是非法字符,否则一律不用引号. 不要将不同目的的语句,合并成一行. 不要省略句末的分号,哪怕一行只有一个语句. 不要使用自增(++)和自减(--)运算符,用+=和-=代替. 不要使用"相等"(==)运算符,只使用"严格相等"(===)

  • 培养自己的php编码规范

    为什么我们要培养自己的编码规范? 我们写代码的时候,一个好的编码规范,对我们来说能够起到很多意向不到的效果.至少会有一下的好处: 1.提高我们的编码效率.整齐划一的代码方便我们进行复制粘贴嘛! 2.提高代码的可读性. 3.显示我们专业.别人看到了我们的代码,发现整个代码的书写流程都整齐划一,瞬间逼格就上去了! 4.方便团队协同工作.大家使用同一的规范,这样就消除了五花八分的书写方式,同一协调! 编码规范包含两大块,代码规范和注释规范 其实我们所写的php脚本,其实也就是由两大块组成的,即对代码的

  • 浅谈Android编码规范及命名规范

    前言: 目前工作负责两个医疗APP项目的开发,同时使用LeanCloud进行云端配合开发,完全单挑. 现大框架已经完成,正在进行细节模块上的开发 抽空总结一下Android项目的开发规范:1.编码规范 2.命名规范 注:个人经验,经供参考 一.Android编码规范 1.学会使用string.xml文件 在我看来,当一个文本信息出现的次数大于一次的时候就必须要使用string.xml 比如一个保存按钮 , 不规范写法: <Button android:id="@+id/editinfo_b

  • Javascript 编码约定(编码规范)

    1.使用 strict 模式 在一个作用域(包括函数作用域.全局作用域)中,可以使用 "use strict"; 来开启 strict 模式. 2.缩进 用 Tab 键进行代码缩进,以节约代码大小,使用4个空格的宽度来进行缩进(JSLint 建议). 3.符号 1) 大括号 与语句放同一行,放于最后面:仅有一行语句,也使用大括号: if (true) { //true } else { //false } while (true) { //alert(1); } 2) 空格 在逗号.分

  • JAVA程序员不得不留意的编码规范

    01 规范存在的意义 应用编码规范对于软件本身和软件开发职员而言尤为重要,有以下几个原因: 好的编码规范可以尽可能的减少一个软件的维护本钱 , 并且几乎没有任何一个软件,在其整个生命周期中,均由最初的开发职员来维护: 好的编码规范可以改善软件的可读性,可以让开发职员尽快而彻底地理解新的代码: 好的编码规范可以最大限度的进步团队开发的合作效率: 长期的规范性编码还可以让开发职员养成好的编码习惯,甚至锻炼出更加严谨的思维: 02 命名规范 1. 一般概念 尽量使用完整的英文描述符 采用适用于相关领域

  • golang语言编码规范的实现

    本规范旨在为日常Go项目开发提供一个代码的规范指导,方便团队形成一个统一的代码风格,提高代码的可读性,规范性和统一性.本规范将从命名规范,注释规范,代码风格和 Go 语言提供的常用的工具这几个方面做一个说明.该规范参考了 go 语言官方代码的风格制定. 一. 命名规范 命名是代码规范中很重要的一部分,统一的命名规则有利于提高的代码的可读性,好的命名仅仅通过命名就可以获取到足够多的信息. Go在命名时以字母a到Z或a到Z或下划线开头,后面跟着零或更多的字母.下划线和数字(0到9).Go不允许在命名

  • 一文了解Go语言中编码规范的使用

    每个语言都有自己特色的编码规范,学习该语言的命名规范,能让你写出来的代码更加易读,更加不容易出现一些低级错误. 本文根据个人编码习惯以及网络上的一些文章,整理了一些大家能用上的编码规范,可能是一些主流方案,但不代表官方,这一点先声明一下. 1. 文件命名 由于 Windows平台文件名不区分大小写,所以文件名应一律使用小写 不同单词之间用下划线分词,不要使用驼峰式命名 如果是测试文件,可以以 _test.go 结尾 文件若具有平台特性,应以 文件名_平台.go 命名,比如 utils_ wind

  • PHP编码规范的深入探讨

    缩进与空白字符(Indenting and Whitespace)使用 2 个空格而不使用 tab 键进行代码缩进(notepad++, Eclipse 等编辑器均支持此项配置);行尾不应该有空白字符应使用 \n (Unix换行符),而不是 \r\n (Windows 换行符)所有文件均应以一个空行结尾 运算符(Operators)所有二元运算符(二个值之间的运算符),如 +, -, =, !=, ==, > 等等,在运算符两端均需留有一个空格,如应该使用 $foo = $bar 而不是 $fo

  • 讲的非常不错的PHP编码规范第1/3页

    注:这是从PHPCMS开发文档里看到编码规范,虽名为PHPCMS的开发规范,但我觉得所有的PHP编程都该如此.写了那么多PHP,很多编码对照这规范都感觉欠缺很多,今后一定要对照纠正. Phpcms 编码规范 1. 引言-. 2 2. 适用范围-. 2 3. 标准化的重要性和好处-. 3 4. PHP编码规范与原则-. 3 4.1. 代码标记- 3 4.2. 注释- 3 4.3. 书写规则- 4 4.3.1. 缩进- 4 4.3.2. 大括号{}.if和switch. 4 4.3.3. 运算符.小

  • 浅谈JavaScript编程语言的编码规范

    JavaScript 编程语言作为最流行的客户端脚本语言,早已被众多 Web 开发人员所熟悉.随着 Web2.0 时代的到来和 Ajax 技术的广泛应用,JavaScript 也逐渐吸引着更多的视线.工作中要求越多的是对 JavaScript 语言的深入学习,灵活运用,和对编码质量的保证. 对于熟悉 C/C++ 或 Java 语言的工程师来说,JavaScript 显得灵活,简单易懂,对代码的格式的要求也相对松散.很容易学习,并运用到自己的代码中.也正因为这样,JavaScript 的编码规范也

  • 5 种JavaScript编码规范

    什么是编码规范 编码规范就是指导如何编写和组织代码的一系列标准.通过阅读这些编码规范,你可以知道在各个公司里代码是如何编写的. 我们为什么需要编码规范 一个主要的原因是:每个人写代码的方式都是不同的.我可能喜欢这么写,而你喜欢用另一种方法写.如果我们只处理自己的代码,这样并没有什么问题.但如果有成千上万的程序员同时在一个代码库上面工作呢?如果没有规范,事情很快会变得一团糟.代码规范可以让新人迅速的熟悉相关的代码,并且也能写出让其他程序员简单易懂的代码. Airbnb JavaScript Sty

  • 关于go语言编码需要放到src 文件夹下的问题

    golang中GOPATH的简单理解 1.为什么要配置GOPATH 配置GOPATH的用意是为了方便项目的部署和构建,以及可以直接使用go get 命令下载第三方的包到自己的项目的src下和相关的执行文件bin目录,和中间文件pkg src :项目的源代码 pkg :编译后的生成文件 bin : 编译后的可执行文件 如果你只是想单独的写个go代码可以不设置GOPATH 2.结合GoLand来讲解GOPATH 2.1:使用goland创建一个gose项目,(可以不配置GOPATH) * 环境变量中

  • python基础之编码规范总结

    一.PEP 8规范 官方文档:https://legacy.python.org/dev/peps/pep-0008/ 中文翻译: https://www.jb51.net/article/103944.htm 二.缩进 每一级缩进4个空格. 续行应该与包裹元素对齐,要么使用圆括号,方括号,花括号内的隐式行连接来垂直对齐,要么使用挂行缩进对齐.当使用挂行缩进对齐时,应该考虑到第一行不应该有参数,以及使用缩进以区分自己是续行. 对齐缩进(左右括号对齐) def long_function_name

随机推荐