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

爱被打了一巴掌 2024-04-27 15:48 165阅读 0赞

> 今天和一个小伙伴偶尔聊了两句，聊到现在工作的开发语言，大学时接触的第一个语言应该是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) {
         ...

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

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

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

// Package regexp implements a simple library 
    // for regular expressions.
    package regexp

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

（即大写开头的变量或者函数）

#### 最好有文件级别的注释 ####

【可选】注释应该位于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>

### 2. 命名规范 ###

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

#### 2.1 普通变量命名 ####

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

#### 2.2 包及包内文件命名 ####

*  尽量小写单词，缩写，不允许存在下划线或者驼峰式结构
 *  包内文件名基本和上条保持一致，允许下划线连接单词的形式，如

package pbft
    pbft_proto.go

#### 2.3 接口命名 ####

*  对于只包含单个函数的接口命名，一般以函数名加上er 或者er类似物作为后缀，如

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

*  对于两个函数的接口，一般结合二者，如

type WriteFlusher interface {
        
        Write([]byte) (int, error)
        Flush() error
    }

*  对于三个及以上函数命名，应该选取有意义的名称，类似其他面向对象中的类或者接口的取名方式

#### 2.4 函数相关命名 ####

*  函数名采用驼峰结构，视其可见性设置函数名首字母大小写
 *  函数返回值建议使用命名的方式（除非返回值异常简单），函数返回值变量命名尽量简洁，以小写字母开头
 *  Go中默认不提供Gettter/Setter方法， 对于Getter方法建议直接大写变量首字母作为方法名，Setter方法建议Set+变量名（首字母大写），如

owner := obj.Owner()
    if owner != user {
        
        obj.SetOwner(user)
    }

*  函数的接收者命名，简洁的单词或者接口的缩写，不要使用self,this, me 等没有具体意义的单词，如

func (rr *roundRobin) watchAddrUpdates() error {
        ...}

*  函数接收者的类型默认为指针类型，某些本身就是引用类型的除外(如：func, map,slice或者chan), 下列情况下必须以指针作为接收者
    
     *  接收者是一个结构体，并且结构体中包含 sync.Mutex或者类似同步域
     *  接收者是结构体，且结构体比较大

### 3. 代码控制块规范 ###

#### 3.1条件控制语句if ####

*  if 的条件临时变量的创建方式，默认如下

if err := file.Chmod(0664); err != nil {
        
        return err
    }

*  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)

#### 3.2 循环控制语句for ####

*  以简明的方式声明局部变量

sum := 0
    for i := 0; i < 10; i++ {
        
        sum += i
    }

#### 3.3 循环控制语句 range ####

*  访问 array, slice, string, or map 或者channel 优先使用range 语法

for key, value := range oldMap {
        
        newMap[key] = value
    }

*  如上个例子如果只需要value， key可用下划线替代 \_, 或者只需要key的情况可以省略 ,value 如

sum := 0
    for _, value := range array {
        
        sum += value
    }
    
    for key := range m {
        
        if key.expired() {
        
            delete(m, key)
        }
    }

### 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.
    }

*  尽量不要使用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")
        }
    }

### 5.日志打印 ###

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

### 6.代码长度限制 ###

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

## 参考资料 ##

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

--------------------

## 想要更多资料 ##

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

### go的一些pdf ###

![在这里插入图片描述][e5f04875ad0a422da1d381fce4df79c0.png]

### 更多资料 ###

![在这里插入图片描述][4dffa026eaa14a03b3448c41a38e020d.png]

### 欢迎来拿资料 ###

![在这里插入图片描述][a8beb043f0bd4d419e0662e206d359a7.gif_pic_center]

--------------------

## 书籍推荐 ##

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

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

![在这里插入图片描述][2fb543cbfd6f4bdead96c975dd301e32.jpeg_pic_center]

### 内容介绍 ###

《深入浅出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本 评论区抽1位小伙伴送书  
? 活动时间：截止到 2023-12-21 19:00:00  
?抽奖方式：利用网络公开的在线抽奖工具进行抽奖  
?**参与方式：关注、点赞、收藏，评论 “从入门到入狱，GoGoGo”**  
————————————————

? 注：活动结束后，会私信中奖粉丝的，各位注意查看私信哦！

### 自主购买 ###

小伙伴也可以访问链接进行自主购买哦~  
直达京东购买链接?：[《深入浅出Go语言核心编程》][Go]

--------------------

## 最后 ##

>  *  **好看的灵魂千篇一律，有趣的鲲志一百六七！**
>  *  如果觉得文章还不错的话，可以**点赞+收藏+关注** 支持一下，**[鲲志的主页][Link 1]** 还有很多有趣的文章，欢迎小伙伴们前去点评
>  *  如果有什么需要改进的地方还请大佬指出❌

![在这里插入图片描述][1282d0d8cd384b1cb81550f0bcdd7254.gif_pic_center]

[Golang]: https://segmentfault.com/a/1190000000464394
[Effective Go]: https://golang.org/doc/effective_go.html
[CodeReviewComments]: https://github.com/golang/go/wiki/CodeReviewComments
[e5f04875ad0a422da1d381fce4df79c0.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/27/e00f3cf8ffd74eb48185fd9a45690b86.png
[4dffa026eaa14a03b3448c41a38e020d.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/27/3ff115fd3c144c03be851d1db72c96ef.png
[a8beb043f0bd4d419e0662e206d359a7.gif_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/27/2cdd9680c9fe4bffae99c1893817f398.gif
[2fb543cbfd6f4bdead96c975dd301e32.jpeg_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/27/0403278509dd403cae806f5618744b7f.jpeg
[Go]: https://item.jd.com/14307426.html
[Link 1]: https://kunzhi.blog.csdn.net/
[1282d0d8cd384b1cb81550f0bcdd7254.gif_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/27/a954258b4c3842c98cdf8f688b930c8a.gif