您现在的位置是:首页 > 技术教程 正文

【送书活动五期】Go语言开发规范指南

admin 阅读: 2024-03-18
后台-插件-广告管理-内容页头部广告(手机)

今天和一个小伙伴偶尔聊了两句,聊到现在工作的开发语言,大学时接触的第一个语言应该是html,系统且简单的学习了前端语言,之后伴随着学校的课程,C++、C#、Java都有涉及,然后就一直已Java为主了,也是在今年,有机会做go语言开发,现在算是java/go双语言开发了。
但go语言自学没一周就开始做go项目了,截止今天有四个月左右了,该专栏却迟迟没有新文章收入,今天就聊聊我这段时间学习+总结的一些Go语言开发规范吧

目录

  • Go语言开发规范指南
    • 1. 注释规范性
      • 不允许中文注释
      • 注释的风格可以选择`//` 或者 `/**/`
      • 每个程序包需要有包级注释
      • 任何一个包外可见的变量或者方法应该需要注释
      • 最好有文件级别的注释
    • 2. 命名规范
      • 2.1 普通变量命名
      • 2.2 包及包内文件命名
      • 2.3 接口命名
      • 2.4 函数相关命名
    • 3. 代码控制块规范
      • 3.1条件控制语句if
      • 3.2 循环控制语句for
      • 3.3 循环控制语句 range
    • 4.错误处理
    • 5.日志打印
    • 6.代码长度限制
  • 参考资料
  • 想要更多资料
    • go的一些pdf
    • 更多资料
    • 欢迎来拿资料
  • 书籍推荐
    • 书籍名称:《深入浅出Go语言核心编程》
    • 内容介绍
    • 适合人群
    • 如何领书
    • 自主购买
  • 最后

Go语言开发规范指南

废话不多说,直接开始干货

本规范制定主要用于开发以及代码review 时进行参考,保证代码开发的一致性与规范性

1. 注释规范性

不允许中文注释

注释的风格可以选择// 或者 /**/

其中前者适合单行注释,后者适合注释的正文应该以被注释的内容作为开头,例如

// Request represents a request to run a command. type Request struct { ... // Encode writes the JSON encoding of req to w. func Encode(w io.Writer, req *Request) { ...
  • 1
  • 2
  • 3
  • 4
  • 5

注释文本应该以点号结束(方便godoc导出),参考上面例子

每个程序包需要有包级注释

包内任一文件内写即可,注释的位置放在package 前面且之间 不可以有空行

// Package regexp implements a simple library // for regular expressions. package regexp
  • 1
  • 2
  • 3

任何一个包外可见的变量或者方法应该需要注释

(即大写开头的变量或者函数)

最好有文件级别的注释

【可选】注释应该位于import 和文件内代码之间的部分,例如

import ( "fmt" "github.com/golang/protobuf/proto" "github.com/op/go-logging" ) /* 文件级别的注释 This file implement the API of consensus which can be invoked by outer services. */ // package-level logger var logger *logging.Logger func init() { logger = logging.MustGetLogger("consensus/pbft") } </code>
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20

2. 命名规范

命名的规范性包括普通变量、结构体、指针类型等。

2.1 普通变量命名

  • 不允许拼音命名
  • go中的命名推崇简洁,可以使用缩写方式,缩写表意不明者请予以注释
  • 不要以下划线或者数字开头
  • 全局变量以及参数变量可以驼峰式结构
  • 首字母大小写视变量可见范围而定

2.2 包及包内文件命名

  • 尽量小写单词,缩写,不允许存在下划线或者驼峰式结构
  • 包内文件名基本和上条保持一致,允许下划线连接单词的形式,如
package pbft pbft_proto.go
  • 1
  • 2

2.3 接口命名

  • 对于只包含单个函数的接口命名,一般以函数名加上er 或者er类似物作为后缀,如
type Reader interface { Read(p []byte) (n int, err error) }
  • 1
  • 2
  • 3
  • 对于两个函数的接口,一般结合二者,如
type WriteFlusher interface { Write([]byte) (int, error) Flush() error }
  • 1
  • 2
  • 3
  • 4
  • 对于三个及以上函数命名,应该选取有意义的名称,类似其他面向对象中的类或者接口的取名方式

2.4 函数相关命名

  • 函数名采用驼峰结构,视其可见性设置函数名首字母大小写
  • 函数返回值建议使用命名的方式(除非返回值异常简单),函数返回值变量命名尽量简洁,以小写字母开头
  • Go中默认不提供Gettter/Setter方法, 对于Getter方法建议直接大写变量首字母作为方法名,Setter方法建议Set+变量名(首字母大写),如
owner := obj.Owner() if owner != user { obj.SetOwner(user) }
  • 1
  • 2
  • 3
  • 4
  • 函数的接收者命名,简洁的单词或者接口的缩写,不要使用self,this, me 等没有具体意义的单词,如
func (rr *roundRobin) watchAddrUpdates() error {...}
  • 1
  • 函数接收者的类型默认为指针类型,某些本身就是引用类型的除外(如:func, map,slice或者chan), 下列情况下必须以指针作为接收者
    • 接收者是一个结构体,并且结构体中包含 sync.Mutex或者类似同步域
    • 接收者是结构体,且结构体比较大

3. 代码控制块规范

3.1条件控制语句if

  • if 的条件临时变量的创建方式,默认如下
if err := file.Chmod(0664); err != nil { return err }
  • 1
  • 2
  • 3
  • if 语句中如果存在对错误信息的判断,遇到错误及时返回,由于异常流程及时返回,正常流程不需要存在else{}代码块,例如
f, err := os.Open(name) if err != nil { return err } d, err := f.Stat() if err != nil { f.Close() return err } codeUsing(f, d)
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10

3.2 循环控制语句for

  • 以简明的方式声明局部变量
sum := 0 for i := 0; i < 10; i++ { sum += i }
  • 1
  • 2
  • 3
  • 4

3.3 循环控制语句 range

  • 访问 array, slice, string, or map 或者channel 优先使用range 语法
for key, value := range oldMap { newMap[key] = value }
  • 1
  • 2
  • 3
  • 如上个例子如果只需要value, key可用下划线替代 _, 或者只需要key的情况可以省略 ,value 如
sum := 0 for _, value := range array { sum += value } for key := range m { if key.expired() { delete(m, key) } }
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10

4.错误处理

  • 在重要函数,特别是作为lib提供其他服务的组件中需要显示返回错误信息
  • 对于有错误返回的函数的调用必须进行错误判断及处理,实现返回错误的函数错误信息应简洁明确,例如 open /etc/passwx: no such file or directory 这种 <动作 + 操作对象 + 错误提示> 的方式比较推荐
  • 为了方便错误的处理,可以自定义错误类型,使用switch的方式进行统一的错误处理,如
type error interface { Error() string } // PathError records an error and the operation and // file path that caused it. type PathError struct { Op string // "open", "unlink", etc. Path string // The associated file. Err error // Returned by the system call. }
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 尽量不要使用Panic处理错误,两种情况除外:1.未知错误发生,2.系统关键组件初始化错误,如
// 1. unkown error switch s := suit(drawCard()); s { case "Spades": //... case "Hearts": //... case "Clubs": //... default: panic(fmt.Sprintf("INVALID suit %q", s)) } // 2. key init var user = os.Getenv("USER") func init() { if user == "" { panic("no value for $USER") } }
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18

5.日志打印

  • 日志输出格式需要基本统一格式
  • 日志的输出级别仔细斟酌,特别是保证生产环境下不输出无效信息以及程序运行内部细节信息(如:某些具体数据结构)
  • 日志级别设置应该灵活,能够通过配置文件进行配置(后续需要一个日志模块支持)

6.代码长度限制

  • 避免过多参数,超过4个参数即可视为过多
  • 避免过长函数(超过50行),经验表明“每当感觉需要以注释来说明点什么的时候,我们把需要说明的东西写进一个独立函数中”
  • 避免过大的单文件组织

参考资料

  • 《Golang编码规范》
  • 《Effective Go》
  • 《CodeReviewComments》
  • 《Go程序设计语言》(艾伦A.A.多诺万, 布莱恩W.柯尼汉)
  • 《重构——改善既有代码的设计》( Martin Fowler)

想要更多资料

鄙人有常年累月收集各种资料的习惯,最近正在整合内容,后续会统一放到公众号 鲲志说 上,想要的大佬可以关注获取,如果有需要的资料,但我暂时没有,也可以留言,我会去找

go的一些pdf

在这里插入图片描述

更多资料

在这里插入图片描述

欢迎来拿资料

在这里插入图片描述


书籍推荐

  • 深入浅出Go语言的众多关键特性,并提供大量场景示例,对于刚接触或转型Go编程的读者是一本很友好的上手指南。
  • 涉及内容新颖而广泛,包括语法结构、面向对象、并发编辑、上下文机制、网络编程、Go汇编以及流行框架等。
  • 不仅讲解Go语言的编程方法与开发技巧,而且力图解读Go语言的设计思想,带领读者探究Go语言的本质。
  • 三位作者都是一线长期使用Go语言的资深开发人,他们的经验是本书质量的保证,希望各位读者能通过阅读本书收获更多

书籍名称:《深入浅出Go语言核心编程》

在这里插入图片描述

内容介绍

《深入浅出Go语言核心编程》是一本全面而深入的Go语言学习手册,涵盖了Go语言的诸多关键特性,包括语法结构、内存原理、并发、上下文机制与框架应用等。

本书共20章。第1章引导读者快速搭建开发环境,详细介绍Go语言的环境配置及编译运行的具体细节。第2~5章详细讨论Go语言独特的变量、常量、常用数据类型和流程控制,并重点解析复杂类型的底层实现机制。第6~8章讲解Go语言的函数及如何实现面向对象编程,打通Go语言面向过程和面向对象编程之间的桥梁。第9~12章探讨Go语言的一些高级话题,包括并发、上下文、反射、泛型等。第13~15章探讨Go语言的I/O、网络编程及RPC通信等编程场景。第16~18章是Go语言的扩展话题,涵盖了内存管理、正则表达式和Go语言的汇编。第19章和第20章重点探讨了Go语言在日常开发中的典型应用,主要介绍HTTP框架Gin的使用,以及如何利用Go语言开发一个综合项目。

适合人群

《深入浅出Go语言核心编程》内容丰富,由浅入深,既适合初次接触Go语言的新手,也适合有一定经验的软件开发人员阅读。

如何领书

————————————————
本次本篇文章送书

标签:
声明

1.本站遵循行业规范,任何转载的稿件都会明确标注作者和来源;2.本站的原创文章,请转载时务必注明文章作者和来源,不尊重原创的行为我们将追究责任;3.作者投稿可能会经我们编辑修改或补充。

在线投稿:投稿 站长QQ:1888636

后台-插件-广告管理-内容页尾部广告(手机)
关注我们

扫一扫关注我们,了解最新精彩内容

搜索