文档章节

程序员自我修炼(二) - 如何编写合格代码(下)

ali安东尼
 ali安东尼
发布于 2017/09/07 15:23
字数 1319
阅读 3
收藏 0

在《如何编写合格代码》的上篇中的开头,我给大家分享了对于“合格的代码” 的定义。

在本文的开头,不妨先让大家重温一下:

满足要求定义的初始化规则代码清晰简洁,没有思维逆反的逻辑或者刻意为之的陷阱代码尽可能控制代码风险合理的代码注释合理的标准化接口定义合,杜绝误用或者滥用

关于前三点的具体注意事项和例子,之前已经有所阐述。(有所忘记的读者可以再重读上篇)

接下来,我将会继续阐述剩下的两点守则。

合理的代码注释

当一个经验丰富的工程师第一眼接触到不合格的代码时,就会下意识地有所察觉。而引起这种“不适感”的很大一个可能原因,就是缺乏合理简洁的注释和排版。

我们在编程工作中应该时常会遇到这样的场景:

当我们编写一个函数后,发现自己应该为函数名或者变量名额外注释说明。

    -那可能是因为你当初定义的变量和函数名称太过随意和模糊;

当我们为函数功能做注释的时候,发觉函数的描述涉及到的功能内容非常多而繁杂。

    -那可能是因为你缺乏架构设计,把太多功能塞在了一个函数里了;

当我们洋洋洒洒写下几千行代码后,发现需要大段的注释才能阐述清楚自己写的代码对应的逻辑和功能。

    -那么这段代码基本上十有八九是写得有问题,需要重构;

根据我的开发经验,除非极其简单到一目了然的代码,否则编写完后都必须要养成习惯添加足够的注释。

只有充分的注释,才能让阅读你代码的人能更真切快速了解到函数的功能、输入、输出是什么,有没有副作用和风险等等。这些如果缺乏注释的话,往往需要耗费阅读者很多的时间,浪费很多的精力才能有所重现和领悟,极大降低代码的使用效率。

而在编写注释的过程中,即意味着你需要站在另外一个角度来审视自己的代码。而往往在这个时候,通过编写注释的过程,你会对自己代码不合理的地方有所觉察,进而把自己的代码修正得更完善。

写注释是一门看似最简单,实则高深莫测的学问。无论是格式的定义,描述的语言组织能力,都无不体现着编程人员的专业素养。

代码的接口定义合理

首先我们看什么是接口?

从软件开发的角度看:宏和函数是接口,类和数据结构是接口,库(library)和包(package)是接口,环境变量是接口,消息类型和网络协议是接口,系统调用是接口,软硬中断是接口,EABI 是接口。

所以只要我们在写代码,我们就无时无刻不和接口打交道,也时时刻刻在创建新的接口。

合格的代码的必要条件是有合理的接口。

什么是合理的接口?我认为必须要符合以下的条件

合理的名称

    -合理的名称的重要性是不言而喻的,这样才可以让使用接口的人不会产生不解和困惑。

合理的输入输出       -合理的输入输出是指接口不要期待过于复杂的输入(比如函数的参数不宜超过五个),如无必要,不要依赖输入以外的数据,而且输入参数包含的数据只需刚好满足相关的需求即可,不要传入无关紧要的数据;对于输出,和输入的要求类似,不要输出会让调用者感到困惑的结果。

符合惯例

    -符合惯例是接口设计中非常重要的原则。比如在有些语言中,size() 按惯例是个 O(1) 的操作,而length() 是 O(n) 的操作。那么你在为你的数据结构提供接口时,也要遵循这个约定,这样使用者才不会困惑,也不会误用。

作为一个优秀的程序员,要时时刻刻为你的代码负责,要时时刻刻为你的接口负责,让用户只能正确地、轻松地使用我们的成果产出。

作为一个合格的程序员,我们应该不断写出合格的,优秀的代码,而不是在这个信息时代中堆砌更加多的数据废物。

让我们一起为成为一名优秀的程序员而努力。

想要学习更多的程序员技巧,请继续关注后续的连载文章。

由睿江云人员提供,想了解更多,请登陆www.eflycloud.com

© 著作权归作者所有

共有 人打赏支持
ali安东尼
粉丝 3
博文 192
码字总数 173101
作品 0
广州
私信 提问
如何让编程产能翻二番?

软件开发过程有一个很自然的比喻:建楼房,要画图纸、搭架构、砌砖头。这个比喻大体说得过去,问题是,这个“砖头”绝非普通的砖头,具有以下特性: 一、每一块都由手工制作; 二、每一块的材...

dellfox
2014/05/08
0
0
工作日志_Index

1 程序员的自我修养 如何成为一个合格的 Java程序员 程序员如何提升自已 程序员如何学会沟通技巧 思维提升:思维广度,深度,高度,远度 大牛养成指南(1):吃的草够多,你也能成为大牛如何成为...

无寄语
2016/08/18
13
0
如何从一个优秀的Java程序员变成一个高薪架构师

做了4年的java程序员,一直考虑以后的发展方向。感觉不适合走管理路线的人,所以考虑继续在技术方面深入下去。 相信好多程序员都有相同的感觉,做了好多年代码民工,感觉自己每天都在重复着相...

禁区铁铍人
2017/12/09
0
0
转让一些经典书籍~

那些年,我们追过的.NET书籍 工作三年买了很多书,最近准备搬家才发现真是累赘,所以想把看完的书低价出售给需要的同学们. 书籍基本都是九成新,大部分都是原版经典书籍以及一些经典的国内书籍,...

Evo
2013/09/09
1K
30
编程的艺术门槛

编程是门艺术,这个说法由来已久。最近在朱赟的公众号(嘀嗒嘀嗒)读到一篇文章《设计是门逻辑学,然后才是美学》,文中作者漂洋过海追寻艺术,老师却说:“设计不是艺术!”。如果设计都不是...

Fico
2016/07/11
4
0

没有更多内容

加载失败,请刷新页面

加载更多

[LintCode] Serialize and Deserialize Binary Tree(二叉树的序列化和反序列化)

描述 设计一个算法,并编写代码来序列化和反序列化二叉树。将树写入一个文件被称为“序列化”,读取文件后重建同样的二叉树被称为“反序列化”。 如何反序列化或序列化二叉树是没有限制的,你...

honeymose
今天
5
0
java框架学习日志-7(静态代理和JDK代理)

静态代理 我们平时去餐厅吃饭,不是直接告诉厨师做什么菜的,而是先告诉服务员点什么菜,然后由服务员传到给厨师,相当于服务员是厨师的代理,我们通过代理让厨师炒菜,这就是代理模式。代理...

白话
今天
23
0
Flink Window

1.Flink窗口 Window Assigner分配器。 窗口可以是时间驱动的(Time Window,例如:每30秒钟),也可以是数据驱动的(Count Window,例如:每一百个元素)。 一种经典的窗口分类可以分成: 翻...

满小茂
今天
18
0
my.ini

1

architect刘源源
今天
16
0
docker dns

There is a opensource application that solves this issue, it's called DNS Proxy Server It's a DNS server that solves containers hostnames, if could not found a hostname that mat......

kut
今天
16
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部