文档章节

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

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
编程的艺术门槛

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

Fico
2016/07/11
4
0
飞龙的程序员书单 – 思想、工程、架构、职业发展

思想 编程珠玑 编程珠玑,字字珠玑。这本书并不单纯讲解算法,而是由一系列实际问题切入,引导读者理解这些问题并学会解决方法,使用现有的算法,或者程序设计技巧解决问题。本书的特色是通过...

apachecn_飞龙
2016/01/16
0
0

没有更多内容

加载失败,请刷新页面

加载更多

下一页

Nginx防盗链、访问控制、Nginx解析PHP相关配置、Nginx代理

Nginx防盗链 在配置文件里写入以下内容: 用curl测试 访问控制 Nginx限制某些IP不能访问或者只允许某些IP访问。 配置文件写入如下内容: allow 表示允许访问的IP,deny限制访问的IP。 匹配正...

黄昏残影
16分钟前
0
0
自己动手实现RPC服务调用框架

转载 TCP的RPC 引言 本文利用java自带的socket编程实现了一个简单的rpc调用框架,由两个工程组成分别名为battercake-provider(服务提供者)、battercake-consumer(服务调用者)。 设计思路...

雨中漫步的鱼
19分钟前
0
0
Centos6.x安装之后的9件事

Centos6.x安装之后的9件事 这些不是必须都做的,只不过是我个人的习惯,在此记录一下。 1.修改yum源到国内 CentOS系统更换软件安装源 备份你的原镜像文件,以免出错后可以恢复。 mv /etc/yu...

叶云轩
24分钟前
6
0
springboot2 使用jsp NoHandlerFoundException

开发图片上传功能,为验证测试功能是否正常,使用JSP编写表单提交进行测试 开发完成后,请求API提示如下异常: No mapping found for HTTP request with URI [/WEB-INF/jsp/avatar_upload.j...

showlike
30分钟前
0
0
springboot踩坑记--springboot正常启动但访问404

一 spring boot的启动类不能直接放在main(src.java.main)这个包下面,把它放在有包的里面就可以了。 二 正常启动了,但是我写了一个controller ,用的@RestController 注解去配置的controlle...

onedotdot
31分钟前
0
0

没有更多内容

加载失败,请刷新页面

加载更多

下一页

返回顶部
顶部