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


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

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

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

    • 符合逻辑,不一定是最优的代码
    • 不符合逻辑,一定不是好的代码

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

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

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

    小编推荐一个学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语言,接受全面系统的指导。这里有一个交流群推荐给你。

    不论是小白还是进阶者,在这里都能获得成长。群内含有,学习书籍电子书资源,素材包,还有免费教学课程哦~点我进入群聊

  • 相关阅读:
    linux centos 8 为.net core 添加进程守护 Supervisor
    vue-quill-editor安装及使用:自定义工具栏和自定义中文字体,把字体写在html的style中
    nginx参数
    k8s pod 挂载glusterfs报错
    Vue跨域问题解决
    CSS导航菜单(二级菜单)
    CSS导航菜单(一级菜单)
    微信小程序开发正常,真机预览模式错误
    uniapp获取用户OpenId及用户详情
    uniapp 获取用户手机号
  • 原文地址:https://www.cnblogs.com/zm131417-/p/14005642.html
Copyright © 2020-2023  润新知