如何避免自己写的代码成为别人眼中的一坨屎!
普通的工程师堆砌代码,优秀的工程师优雅代码,卓越的工程师简化代码。如何写出优雅整洁易懂的代码是一门学问,也是软件工程实践里重要的一环。笔者推荐三本经典的书籍《代码整洁之道 》、《编写可读代码的艺术》、《重构:改善既有代码的设计》,下文重点将从注释、命名、方法、异常、单元测试等多个方面总结了一些代码整洁最佳实践,大部分是笔者总结于以上三本书中的精华,也有部分是笔者工程实践的总结。篇幅有限,本文将总结性给出一些实践建议,后续会有文章来给出一些代码整洁之道的事例。
一、注释
不要给不好的名字加注释,一个好的名字比好的注释更重要;
不要“拐杖注释”,好代码 > 坏代码 + 好注释;
在文件/类级别使用全局注释来解释所有部分如何工作;
一定要给常量加注释;
团队统一定义标记:
TODO 待处理的问题;
FIXME 已知有问题的代码;
HACK 不得不采用的粗糙的解决方案;
在注释中用精心挑选的输入输出例子进行说明;
注释应该声明代码的高层次意图,而非明显的细节;
不要在代码中加入代码的著作信息,git可以干的事情不要交给代码;
源代码中的html注释是一种厌物, 增加阅读难度;
注释一定要描述离它最近的代码;
注释一定要与代码对应;
公共api需要添加注释,其它代码谨慎使用注释;
典型的烂注释:
不恰当的信息;
废弃的注释;
冗余注释;
糟糕的注释;
注释掉的代码;
唯一真正好的注释是你想办法不去写的注释:
不要有循规式注释,比如setter/getter注释;
不要添加日志式注释,比如修改时间等信息(git可以做的事情);
注释一定是表达代码之外的东西,代码可以包含的内容,注释中一定不要出现;
如果有必要注释,请注释意图(why),而不要去注释实现(how),大家都会看代码;
适当添加警示注释;
二、命名
尽可能使用标准命名方法,比如设计模式,通用学术名词等;
命名要找更有表现力的词:
使用更专业的词,比如不用get而使用fetch或者download;
避免空泛的名字,像tmp;
使用具体的名字来细致的描述事物;
给变量名带上重要的细节,比如加上单位ms等;
为作用域大的名字采用更长的名字,作用域小的使用短名字;
变量类型为布尔值表达加上is,has,can,should这样的词会更明确;
变量名称长短应该与其作用域对应;
别害怕长名称,长而具有描述性的名称比短而令人费解的名称好;
函数名称应该说明副作用,名称应该表达函数,变量或类的一切信息,请不要掩盖副作用,比如CreateAndReturnXXX;
三、方法
函数不应该有100行那么长,20行封顶最好:
if else while等控制语句其中代码块应该只有一行,也就是一个函数调用语句;
函数的锁进层次不应该多于两层;
一个函数只做一件事,一个函数不应该能抽象出另外一个函数;
某个公共函数调用的私有函数紧随其后;
最理想的参数是零参数,最长不要超过三个入参,尽量不要输出参数:
如果函数传入三个及以上参数最好将其抽象为类;
标识参数十分丑陋,向函数传入布尔值用于区分不同业务的做法很丑陋,应该拆分为多个函数;
别返回null值,抛出异常或者返回特殊对象,尽量避免NPE;
别传入null值;
四、异常与错误
抽离try catch包含的代码块,其中代码块抽象为一个函数;
抛出的每个异常,都应当提供足够的环境说明,已便判断错误的来源与处所;
不要将系统错误归咎于偶然事件;
五、并发
分离并发相关代码与其它代码;
严格限制对可能被共享的数据的访问;
避免使用一个共享对象的多个同步方法;
保持同步区域微小,尽可能少设计临界区;
六、单元测试
不要怕单元测试的方法名字太长或者繁琐,测试函数的名称就像注释;
不要追求太高的测试覆盖率,测试代码前面90%通常比后面10%花的时间少;
使用最简单的并且能够完整运用代码的测试输入;;
给测试函数取一个完整性的描述性名字,比如 Test _;
测试代码与生产代码一样重要;
如果测试代码不能保证整洁,你就会很快失去他们;
每个测试一个断言,单个测试中断言数量应该最小化也就是一个断言;
FIRST原则:
快速 Fast;
独立 Independent 测试应该相互独立;
可重复 Repeatable 测试应当在任何环境中重复通过;
自足验证 Self-Validating 测试应该有布尔值输出;
及时 Timely 最好的方式是TDD;
七、代码结构
代码行长度控制在100-120个字符;
可能用大多数为200行,最长500行的单个文件构造出色的系统;
关系密切的代码应该相互靠近:
变量声明应该靠近其使用位置;
若某个函数调用了另外一个,应该把他们放在一起,而且调用者应该放在被调用者上面;
自上向下展示函数调用依赖顺序;
应该把解释条件意图的函数抽离出来,尽可能将条件表达为肯定形式;
不要继承常量,比如接口中定义常量,不要使用继承欺骗编程语言的作用范围规则;
模块不应了解它所操作对象的内部情况;
DTO(Data Transfer Objects)是一个只有公共变量没有函数的类;
对象暴露行为,隐藏数据;
不要使用“尤达表示法” 如 if(null == obj),现代编译器对if(obj = null)这样的代码会给出警告;
一般情况使用if else,简单语句使用三目运算符;
通常来讲提早返回可以减少嵌套并让代码整洁;
八、设计
类应该足够短小:
类应该满足单一权责原则(SRP),类和模块只有一个修改理由;
类应该只有少量的实体变量;
类应该遵循依赖倒置原则 DIP(Dependency Inversion Principle),类应该依赖于抽象而不是依赖于具体细节;
类中的方法越少越好,函数知道的变量越少越好,类拥有的实体变量越少越好;
通过减少变量的数量和让他们尽量“轻量级”来让代码更有可读性:
减少变量;
缩小变量的作用域;
只写一次的变量更好,如常量;
最好读的代码就是没有代码:
从项目中消除不必要的功能,不要过度设计;
从新考虑需求,解决版本最简单的问题,只要能完成工作就行;
经常性地通读标准库的整个API,保持对他们的熟悉程度;
简单设计:
运行所有测试;
不可重复;
表达了程序员的意图;
尽可能减少类和方法的数量;
以上规则按重要程度排列;
无论是设计系统或者单独模块,别忘了使用大概可工作的最简单方案;
整洁的代码只提供一种而非多种做一件事的途径,他只有尽量少的依赖。明确定义并提供尽量少的API;
减少重复代码,提高表达力,提早构建,简单抽象;
九、小结
本文从注释、命名、方法,单元测试,并发等视角简单给出了一些最佳实践,下文我们会展开来从每个方面介绍更多的实践事例。相信每一个优秀的工程师都有一颗追求卓越代码的心,在代码整洁工程实践上你有哪些好的建议?数百人协作开发的代码如何保证代码整洁一致性?欢迎大家来讨论。
PS:如果觉得我的分享不错,欢迎大家随手点赞、转发。
原文:yq.aliyun.com/articles/598076?utm_content=m_51055
Java团长
专注于Java干货分享
扫描上方二维码获取更多Java干货
如何避免自己写的代码成为别人眼中的一坨屎!相关推荐
- 如何避免自己写的代码成为别人眼中的一坨屎 (摘自微信公众号,顶级程序员)...
从微信公众号上读到一篇文章,记录下来提醒自己也分享给大家~ 一.注释 不要给不好的名字加注释,一个好的名字比好的注释更重要: 不要"拐杖注释",好代码 > 坏代码 + 好注释 ...
- 过年了,是不是应该写点代码祝福别人
(function(a) { // 控制台输出信息if (!a) return;var msg = "%c祝福大家新年快乐,\n狗年大吉\n ------http://www.cnblogs ...
- 在别人写的代码上做修改我是这样保证正确性
引子 9年前我入职一家公司,团队里都是之前公司的原同事,彼此都很熟,对各人的能力也都很了解.我当时负责整个公司的搜索引擎.上班第一天,我在看之前的遗留代码.原同事过来问我:"你是打算用这个老 ...
- stream流常用方法_Java8 中用法优雅的 Stream,怪不得我之前总是看不懂别人写的代码!...
Java8的新特性主要是Lambda表达式和流,当流和Lambda表达式结合起来一起使用时,因为流申明式处理数据集合的特点,可以让代码变得简洁易读 放大招,流如何简化代码 如果有一个需求,需要对数据库 ...
- 转程序员,都去写一写前端代码吧
转自: http://www.oschina.net/news/36972/programmer-write-frond-end-code 你可以认为我是一个极端的人,就像有许多人专注于自己的领域而不 ...
- 不写一行代码,也能玩转Kaggle竞赛?
整理 | Jane 出品 | AI科技大本营(ID:rgznai100) [导读]AI科技大本营会给大家分享一些 Kaggle 上的资源,如 Kaggle 开放的数据集,也会分享一些好的竞赛方案或有意 ...
- 同事说,我写Java代码像写诗
文章来源:http://33h.co/kntu3 前几天空闲时间写了一遍关于平时自己写代码的一些习惯,这里跟大家分享一下. 定义配置文件信息✦ 有时候我们为了统一管理会把一些变量放到 yml 配置文件 ...
- python数据分析神器_牛逼啊!一个随时随地写Python代码的神器
作者: Leoxin 公众号:菜鸟学Python 现在学Python的人越来越多,很多小伙伴都非常有激情.利用碎片时间随时随地学习Python, 大家知道Python是一门编程语言,但是学语言光看不练 ...
- 千万不要相信程序员在加班时间写的代码!
其中最重要的就是这条:不要相信一个程序员在加班时间写出来的代码. (软件工程的学说表明,连正常时间好好写的代码,也不要太相信.不过这不是本文的重点,略过不提.) (不懂代码的人,看到本文中的Java代 ...
最新文章
- 使用Linux的lsblk命令列出块设备信息
- tensorflow学习笔记二——建立一个简单的神经网络拟合二次函数
- 代码规范:在Keil5中使用代码格式化工具Astyle(插件)
- FZU OJ:2230 翻翻棋
- 前端学习(77):css中常见margin塌陷问题之解决办法
- 华为python有必要学吗_【华为云技术分享】这个 Python 库有必要好好学学
- 关于proxy模式下,@Transactional标签在创建代理对象时的应用
- [Android]Notification汇总
- 关于【CDQ分治】的学习
- vc6.0c语言如何延迟清屏时间,[转载]关于在vc6.0中输出运动的笑脸问题
- PLC通过控制器控制步进电机
- 毕业设计开发日志,基于ARM的嵌入式人脸识别系统的设计与实现
- moss下载_无法为增值税MOSS混乱提供“简单的技术解决方案”
- 《老司机,带带我》之考驾照
- Excel PivotTable 使用心得手顺分享(一)
- 关于最近很火的Python圣诞树
- 常见数据同步工具的对比
- 新玺配资:股票波段操作中的操作法则
- 机器学习最易懂之贝叶斯模型详解与python实现
- 暑假N天乐【比赛篇】 —— 2019牛客暑期多校训练营(第六场)
热门文章
- 【金猿人物展】南讯股份陈碧勇: 关于零售企业数字化变革与数据安全的思考...
- python UDP广播
- 第 5 章 Resizable(调整大小)组件
- 浅析MySQL中concat以及group_concat的使用
- A ConvNet for the 2020s 简单翻译/理解
- parseInt、valueOf、intValue和toString的区别
- mysql插入数据中文_mysql插入中文数据的方法
- 弘辽科技:京东店铺层级划分标准,怎么优化层级?
- Linux 下非 root 用户 Conda 安装生物信息 R 软件包 MetaboAnalystR 演示
- php直销二叉树,PHP二叉树自动排位算法