go 编程规范

如果没有编程规范会有什么问题？

哪些地方可以需要指定规范？

非编码类规范；编码规范

非编码规范

开源规范

http://www.ruanyifeng.com/blog/2011/05/how_to_choose_free_software_licenses.html

README规范

ReADME 规范是项目的门面，是开发者学习项目首先阅读的，位于项目的根文件下。主要用来介绍项目的功能，安装和使用。

# 项目名称
<!-- 写一段简短的描述项目-->
## 功能特性
<!-- 描述该项目的核心功能点-->
## 软件架构
<!--可以描述下项目的架构-->
## 快速开始
### 依赖检查
<!-- 描述该项目的依赖，比如依赖的包、工具或者其他任何依赖项 -->
### 构建
<!-- 描述如何构建该项目>
### 运行
<!-- 描述如何运行该项目 -->
## 使用指南
<!-- 描述如何使用该项目 -->
## 如何贡献
<!-- 告诉其他开发者如果给该项目贡献源码 -->
## 社区(可选)
<!-- 如果有需要可以介绍一些社区相关的内容 -->
## 关于作者<!-- 这里写上项目作者 -->
## 谁在用(可选)
<!-- 可以列出使用本项目的其他有影响力的项目，算是给项目打个广告吧 -->
## 许可证
<!-- 这里链接上该项目的开源许可证 -->

项目文档规范

项目文档包括一切需要文档化的内容，通常集中放在/docs 目录下。创建项目文档时，通常会预先创建一些目录用来存放不同的文档。好的项目文档具有易读和可以快速定位文档。

开发文档：用来说明项目的开发流程(如何搭建开发环境，构建而二进制文件，测试，部署...)

用户文档：软件的使用文档，对象一般是软件的使用者，内容可根据需要添加。比如，可以包括 API 文档、SDK 文档、安装文档、功能介绍文档、最佳实践、操作指南、常见问题等。

docs
├── devel                            # 开发文档，可以提前规划好，英文版文档和中文版文档
│   ├── en-US/                       # 英文版文档，可以根据需要组织文件结构
│   └── zh-CN                        # 中文版文档，可以根据需要组织文件结构
│       └── development.md           # 开发手册，可以说明如何编译、构建、运行项目
├── guide                            # 用户文档
│   ├── en-US/                       # 英文版文档，可以根据需要组织文件结构
│   └── zh-CN                        # 中文版文档，可以根据需要组织文件结构
│       ├── api/                     # API文档
│       ├── best-practice            # 最佳实践，存放一些比较重要的实践文章
│       │   └── authorization.md
│       ├── faq                      # 常见问题
│       │   ├── iam-apiserver
│       │   └── installation
│       ├── installation             # 安装文档
│       │   └── installation.md
│       ├── introduction/            # 产品介绍文档
│       ├── operation-guide          # 操作指南，里面可以根据RESTful资源再划分为更细的子目录，用来存放系统核心/全部功能的操作手册
│       │   ├── policy.md
│       │   ├── secret.md
│       │   └── user.md
│       ├── quickstart               # 快速入门
│       │   └── quickstart.md
│       ├── README.md                # 用户文档入口文件
│       └── sdk                      # SDK文档
│           └── golang.md
└── images                           # 图片存放目录
    └── 部署架构v1.png

API 接口文档

接口文档又称为 API 文档，一般由后台开发人员编写，用来描述组件提供的 API 接口，以及如何调用这些 API 接口。

接口文档的内容

Word格式的文档：

工具编写

注释生成

MarkDown格式文档

版本规范

语义版本规范(SemVer)

版本格式： 主版本号.次版本号. 修订号

Commit 规范

Commit Message作用

1. 可以让自己或其他开发者能够清晰地知道commit的变更内容，方便快速浏览变更历史
2. 可以基于这些Commit Message进行过滤查找
3. 可以基于规范化的Commit Message 生成Change Log
4. 可以基于某些类型的Commit Message 触发构建或发布流程
5. 确定语义化的版本号

Commit Message 规范

Angular规范

https://www.conventionalcommits.org/en/v1.0.0-beta.4/

Commit Message是语义化的；Commit Message 都会被归为一个有意义的类型，用来说明本次 commit 的类型。

Commit Message 是规范化的：Commit Message 遵循预先定义好的规范，比如 Commit Message 格式固定、都属于某个类型，这些规范不仅可被开发者识别也可以被工具识别。

<type>[optional scope]: <description>
// 空行
[optional body]
// 空行
[optional footer(s)]

Header 是必须的， Body 和Footer可以省略，在以上规范中，必须用括号 () 括起来， [] 后必须紧跟冒号 ，冒号后必须紧跟空格，2 个空行也是必需的。为了更加易读，一般限制message的长度为50/72/100个字符。

fix($compile): couple of unit tests for IE9
# Please enter the Commit Message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
# On branch master
# Changes to be committed:
# ...

Older IEs serialize html uppercased, but IE9 does not...
Would be better to expect case insensitive, unfortunately jasmine does
not allow to user regexps for throw expectations.

Closes #392
Breaks foo.bar api, foo.baz should be used instead

Header

一行 包含3个参数 ： type， scope，subject

type: Development; Profuction

Development：这类修改一般是项目管理类的变更，不会影响最终用户和生产环境的代码，比如 CI 流程、构建方式等的修改。遇到这类修改，通常也意味着可以免测发布。

Production：这类修改会影响最终的用户和生产环境的代码。所以对于这种改动，我们一定要慎重，并在提交前做好充分的测试。

---

Go编码规范

代码风格

代码格式

• 代码都必须用gofmt 进行格式化
• 运算符和操作属之间要留空格
• 建议一行代码不超过120个字符，超过部分，请采用合适的方式换行。
• 文件长度不能超过800行
• 函数长度不超过80行
• import 规范
  • 代码都必须用goimports 进行格式化
  • 不要使用相对路径引入包
  • 包名称与导入路径的最后一个目录名不匹配时，或多个相同包名冲突时，则必须使用导入包名。

jwt //good jwt "github.com/dgrijalva/jwt-go/v4"

• 导入的包建议进行分组，匿名包的引用使用一个新的分组，并对匿名包引用进行说明。

import (
// go标准包
    "fmt"
 // 第三方包
     "github.com/jinzhu/gorm"
     "github.com/spf13/cobra"
     "github.com/spf13/viper"

    // 匿名包单独分组，并对匿名包引用及进行说明
    // import mysqldriver
    _"github.com/jinzhu/gorm/dialects/mysql"

    // 内部包
    v1 "github.com/marmotedu/api/apiserver/v1"
    metav1 "github.com/marmotedu/apimachinery/pkg/meta/v1"
    "github.com/marmotedu/iam/pkg/cli/genericclioptions"
)

声明 初始化和定义

当函数中需要使用到多个变量时，可以在函数开始处使用var声明，在函数外部声明必须使用var,不要使用:=, 容易踩到变量的作用域问题。

var (
Width int
Height int
)

在初始化结构引用时，请使用 &T{} 代替 new(T),以使其以结构初始化一致。

sptr:=&T{Name:"bar"}

struct 声明和初始化格式采用多行，定义如下

type User struct{
    Username string
    Email string
}
user := User{
    Username :"colin",
    Email:"colin",
    Email:"colin404@foxmail.com",
}

相似的声明放在一起，同样适用于常量，变量和类型声明

import (
"a"
"b"
)

尽可能指定容器容量，以便为容器预先分配内存

v := make(map[int]string,4)
v :=make([] string,0,4)