代码编写行为准则，编码是一个认真思考的过程，如何有效提高代码的可读性？

编写代码，实质是在梳理逻辑，为了完善整个逻辑流程，我们借用编程语言的变量、函数、流程控制、循环、注释、方法等串接起来，完善一套系统的逻辑。

为了完善这套逻辑，我们借助了许多工具：设计方法、架构设计、项目组织等。

意识到没有，代码的好坏一定程度上可以从逻辑层面评判。

符合逻辑，不一定是最优的代码

不符合逻辑，一定不是好的代码

从这层面来看，梳理逻辑极为重要，逻辑通了，剩下的就是实现了。

逻辑的串接靠的是编程语言的变量、函数、流程控制、循环、注释等。

本文从这些层面讲述，如何编写可读代码。

0. 规范

绝大多数的人，不会从零完整的完成一个复杂的项目，大多是团队共同合作，完成一个大的项目。

这个时候，假如你是中途参与进来。你在实现逻辑的时候，你是照着自己的逻辑来还是依照团队的风格来。

比如项目组织，命名等...

依照团队的风格来

尤其针对复杂的上线的项目，完整的理解整个项目都存在困难，这个时候，风格统一尤其重要。

是的，这个时候，风格一致性重要，当然具体的实现逻辑，还是应该遵从易于理解这个大方向。

1. 编程语言规范

准则：坚持编程语言的风格

每门编程语言，都存在一定的规范，这个时候，编程语言的整体规范需要遵从。

大家可能会多参考 google 出品的各种编程语言规范。方向没错。

2. 命名

变量

函数

方法

准则：易于理解

如何做到易于理解：

专业的单词：使用领域内的单词

避免空泛的名字

具体的名字

变量名带上更多细节

不使用令人误解的名字

布尔值命名

不建议使用的单词

2.1 领域内的单词

这个和项目相关，比如系统是个智慧零售后台，那么领域内单词多是：顾客、商品、商铺、店员、店长、价格等。

customer

produce

shop

shopLeader

price

2.2 避免空泛的名字

变量的命名一般要赋予一定的意义，极少情况下可以使用没有什么意义的单词。比如最常见的：

var (

 numberOne int

 temp int

 numberTwo int

)

tmp = numberOne

numberOne = numberTwo

numberTwo = tmp

再比如：

var i int

for i=0;i

 fmt.Println(i)

}

这种没什么意义的单词，一般适用于局部作用域。

尽量少用。

2.3 具体的名字

完成什么任务就使用什么单词。一般变量使用名词居多，函数使用动词开头居多。

函数多用动词，变量多用名词

比如：

var toString = func(){}

var serverLoop = func(){}

var pages int

var userName string

2.4 带上更多细节

一般命名不建议过长，也不建议过短，那多长，多短合适呢？

最长三个单词的长度吧

如何带上更多的细节。

尝试使用后缀

尝试使用单位

尝试指向具体的细节

比如：

var timeIntervalMs

var lengthCm

var delaySecs

var sizeMb

var maxKbps

var degreesCw

var numberMax

var numberMin

var numberFirst

var numberLast

赠送几组对仗的后缀：

max/min

first/last

begin/end ...

ServerCanStart() 不如 CanListenOnPort()

2.5 不使用令人误解的词

比如：Filter 在数据库操作中容易使用这个单词，这个单词没有带上更多的细节，实质上在使用的过程中，还是需要查看编写的SQL 语句等才能知道具体的过滤细节。整体思考多了几步。不易让人理解。

建议多读几遍自己命名的单词

2.6 布尔值

提到布尔值，因为就存在两种结果。所有，一般使用是否这样意思的词。

比如：

var (

 ok bool

 notOk bool

)

var (

 is bool

)

var (

 has bool

)

var (

 found bool

)

var (

 should bool

)

var isCompany = func(){}

var isVip = func(){}

var hasSpace = func(){}

2.7 不建议使用的单词

get

read

util

恰恰这几个单词，在写代码中最容易使用。选择替代方案。

赠送一波动词：

- send

deliver、dispatch、announce、distribute、route

- find

search、extract、locate、recover

- start

launch、create、begin、open

- make

create、setUp、build、generate、compose、add、new

3. 设计

一份好的幻灯片演示设计需要考虑什么？

符合场景的配色，确定原始基调

符合场景的事物，借用来表达观念

统一整体风格

对齐、重复、亲密、比较

看到没，幻灯片演示设计，强调场景化，选择适合场景的主体和配色，比如党政风格，当然选择国旗色；比如学术答辩，当然选择蓝色；比如手机发布会，当然使用暗黑科技风格...

所以代码也需要场景化，选择符合场景的单词等

这里以设计的四个规范类比代码的组织。

3.1 对齐

编程语言为什么强调缩进？难道不是为了阅读代码的人更容易看懂代码吗？写代码的人更容易组织代码吗？仅仅是设计者为了好玩？

当然不是。

举例：编写web路由和控制器

// student.go

func Register(r *gin.Group) {

 r.POST("/v1/api/students", PostHandler)

 r.GET("/v1/api/students/:sid", GetHandler)

 r.PATCH("/v1/api/students/:sid", PatchHandler)

 r.PUT("/v1/api/students/:sid", PutHandler)

 r.DELETE("/v1/api/students/:sid", DeleteHandler)

}

放眼望去，确实知道实现什么任务

风格统一

整整齐齐

这个例子可能解释对齐，不够友好。

再举个例子：

CheckFullName("No Such Guy","",  "not match found")

CheckFullName("John",     , "",  "more than one resule")

3.2 重复、亲密、比较

当然，作为程序员，最应该避免的其实就是写重复的代码，一般的做法往往是提炼，将重复的抽象出一个函数之类的。这里的重复，是风格的统一

// teacher.go

func Register(r *gin.Group) {

 r.POST("/v1/api/teachers", PostHandler)

 r.GET("/v1/api/teachers/:tid", GetHandler)

 r.PATCH("/v1/api/teachers/:tid", PatchHandler)

 r.PUT("/v1/api/teachers/:tid", PutHandler)

 r.DELETE("/v1/api/teachers/:tid", DeleteHandler)

}

可以结合比较下 student.go 和 teacher.go

这样的组织方式，讲道理，并不太会给阅读代码的人带来太多的认知负担。

一致的顺序

始终一致的使用，使用户其实阅读一个，类似的都能秒懂

3.3 留白

设计领域页面的设计，并不强调内容越多越好，恰当的在页面上留有空白，使整体设计有呼吸感。

那编程如何实现留白？

恰当的换行，使相似的内容更紧凑

提取，使用方法来组织不规范的东西

代码分段

假如你一个函数需要写 100 多行，不好意思，我可能建议你，不要这么做。

拆分，逻辑梳理、提取方法

尽量维持最长 30～50行左右（这样使屏幕能装载下，一次就能完成的阅读整个函数的逻辑）

4 注释

准则：帮助阅读代码的人对代码了解的和写代码的人一样多

什么时候不需要注释

什么时候需要注释

4.1 什么时候不需要注释

是的，前文的一系列准则，命名啊之类的，是内容，也是注释，通过阅读变量、函数名等就了解了代码完成的任务。

这样的地方不需要注释，因为显而易见，从代码本身就能推断事实。

有时候可能需要考虑是不是命名不好，导致需要注释，这个时候，命名优于注释。

给不好的代码注释，和在错误的路上持续努力一样令人可怕。

4.2 什么时候需要注释

关键点

缺陷点

常量

全局注释

总结性注释

关键点：

有些时候，仅仅靠之前的“表面工作” 已经不能完全能够满足让人易于理解。这个时候需要在关键点添加注释。

缺陷点：

是的，承认自己的代码写的不是最优的，仅仅只是实现，还存在更优的办法，所以需要在有缺点的地方加上注释。

常量：(各编程语言建议常量大写)

给常量注释，赋予了更多的意义。

比如：

NUMTHRADS = 8 // as long as it is >= 2 * number_processors, that is good enough.

好，假如你正在优化代码，看到这注释，是的，你知道该如何调整了。

全局注释：

一般在文件开头，表明文件内代码完成的任务。

总结性注释：

一般函数开头，表明函数代码完成的任务。

其他：

润色语句。言简意赅由于冗长的解释。

以上就是代码表面整洁规范的标准和建议，希望大家都能敲出高效、整洁的代码。