编写代码,实质是在梳理逻辑,为了完善整个逻辑流程,我们借用编程语言的变量、函数、流程控制、循环、注释、方法等串接起来,完善一套系统的逻辑。
为了完善这套逻辑,我们借助了许多工具:设计方法、架构设计、项目组织等。
意识到没有,代码的好坏一定程度上可以从逻辑层面评判。
- 符合逻辑,不一定是最优的代码
- 不符合逻辑,一定不是好的代码
从这层面来看,梳理逻辑极为重要,逻辑通了,剩下的就是实现了。
逻辑的串接靠的是编程语言的变量、函数、流程控制、循环、注释等。
本文从这些层面讲述,如何编写可读代码。
小编推荐一个学C语言/C++的学习裙【 712,284,705】,无论你是大牛还是小白,是想转行还是想入行都可以来了解一起进步一起学习!裙内有开发工具,很多干货和技术资料分享!
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<10;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.
好,假如你正在优化代码,看到这注释,是的,你知道该如何调整了。
全局注释:
一般在文件开头,表明文件内代码完成的任务。
总结性注释:
一般函数开头,表明函数代码完成的任务。
其他:
润色语句。言简意赅由于冗长的解释。
以上就是代码表面整洁规范的标准和建议,希望大家都能敲出高效、整洁的代码。
如果你也想要自学C语言,接受全面系统的指导。这里有一个交流群推荐给你。
不论是小白还是进阶者,在这里都能获得成长。群内含有,学习书籍电子书资源,素材包,还有免费教学课程哦~点我进入群聊