代码整洁之道(一)最佳实践小结
摘要: Any fool can write code that a computer can understand. Good programmers write code that humans can understand. 普通的工程师堆砌代码,优秀的工程师优雅代码,卓越的工程师简化代码。
普通的工程师堆砌代码,优秀的工程师优雅代码,卓越的工程师简化代码。如何写出优雅整洁易懂的代码是一门学问,也是软件工程实践里重要的一环。笔者推荐三本经典的书籍《代码整洁之道 》、《编写可读代码的艺术》、《重构:改善既有代码的设计》,下文重点将从注释、命名、方法、异常、单元测试等多个方面总结了一些代码整洁最佳实践,大部分是笔者总结于以上三本书中的精华,也有部分是笔者工程实践的总结。篇幅有限,本文将总结性给出一些实践建议,后续会有文章来给出一些代码整洁之道的事例。
注释
- 不要给不好的名字加注释,一个好的名字比好的注释更重要
- 不要“拐杖注释”,好代码 > 坏代码 + 好注释
- 在文件/类级别使用全局注释来解释所有部分如何工作
- 一定要给常量加注释
团队统一定义标记
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
- 减少重复代码,提高表达力,提早构建,简单抽象
小结
作为代码整洁之道系列的第一篇,本文从注释、命名、方法,单元测试,并发等视角简单给出了一些最佳实践,下文我们会展开来从每个方面介绍更多的实践事例。相信每一个优秀的工程师都有一颗追求卓越代码的心,在代码整洁工程实践上你有哪些好的建议?数百人协作开发的代码如何保证代码整洁一致性?欢迎大家来讨论。
本文作者:竹涧
阅读原文
本文为云栖社区原创内容,未经允许不得转载。
代码整洁之道(一)最佳实践小结相关推荐
- 代码整洁之道(一)最佳实践小结 1
摘要: Any fool can write code that a computer can understand. Good programmers write code that humans ...
- 【苦练基本功】代码整洁之道 pt4(第10章-第12章)
代码整洁之道 pt4(第10章-第12章) 10 类 10.1 类的组织 10.2 类应该短小 10.2.1 单一权责原则 10.2.2 内聚 10.2.3 保持内聚性就会得到许多短小的类 10.3 ...
- 《代码整洁之道 Clean Architecture》-读书笔记
大家好,我是烤鸭: 关于<代码整洁之道>,记录一下读书笔记. 代码整洁之道 第一章 整洁代码 整洁代码的艺术 第二章 有意义的命名 避免误导 有意义的区分 使用读得出来和可搜索的名字 避免 ...
- java 代码整洁快捷方式_代码整洁之道:你的代码是否足够优雅、整洁、易懂?...
普通的工程师堆砌代码,优秀的工程师优雅代码,卓越的工程师简化代码.如何写出优雅整洁易懂的代码是一门学问,也是软件工程实践里重要的一环.下面从注释.命名.方法,并发等视角简单给出了部分最佳实践.相信每一 ...
- 【苦练基本功】代码整洁之道 pt1(第1章-第3章)
代码整洁之道 pt1(第1章-第3章) 1 整洁代码 1.1 要有代码 1.2 糟糕的代码 1.3 混乱的代价 1.3.1 什么是整洁代码? 2 有意义的命名 2.1 名副其实 2.2 避免误导 2. ...
- 【苦练基本功】代码整洁之道 pt3(第7章-第9章)
代码整洁之道 pt3(第7章-第9章) 7 错误处理 7.1 使用异常而非返回码 7.2 先写try-catch-finally 7.3 使用未检异常 7.4 给出异常发生的环境说明 7.5 依调用者 ...
- 代码整洁之道,不止于程序员需要的职业素养
代码整洁之道,不止于程序员需要的职业素养 最近在读<代码整洁之道>这本书,分享一些我的感悟.首先得说明一下这本书是一本技术类的书籍,大部分内容讲的是纯技艺方面的知识,比如测试驱动开发.阻塞 ...
- 代码整洁之道 Clean Code 读书笔记
目录 代码整洁之道 Clean Code 第一章 整洁代码 第二 三章 命名与函数 第四 五章注释与格式 第六章 对象和数据结构 第七章 错误处理 第八章 边界 第九章 单元测试 第十章 类 第十一章 ...
- 《代码整洁之道》目录—导读
版权声明 代码整洁之道 Authorized translation from the English language edition, entitled Clean Code: A Handboo ...
最新文章
- sql和python还有c语言_Python语言之原生sql整理
- rtsp连接断开_live555学习之RTSP连接建立以及请求消息处理过程
- svn使用经验---不断总结
- 【Tools】python环境操作笔记
- 我的数据分析全系列教程,记录着那些大学奋斗的时光
- 面试题24 二叉搜索树的后序遍历序列
- Day6-------BOM
- 将Visual Studio更新到最新版本
- 哈工大计算机科学与技术邬向前,人工智能学院组队赴哈工大交流学习
- 【ybt金牌导航1-4-3】【luogu P2627】修剪草坪 / Mowing the Lawn G
- Log4j整合阿里云日志服务
- 服务器虚拟机双活,VMware双活数据心解决方案详解.pptx
- 2017年北京邮电大学计算机考研机试试题及答案
- Java日志框架 -- 日志框架介绍、日志门面技术、JUL日志(JUL架构、JUL入门示例、JUL日志级别、JUL日志的配置文件)
- 原神机器人Yunzai Bot搭建
- 好用的办公邮箱是提高工作效率的第一步
- Metal每日分享,颜色转换滤镜效果
- 什么是微型计算机的字长,计算机的字长是指什么
- TPR 教学法是什么?
- linux汇编 lea,汇编指令LEA
热门文章
- python r语言 作图_R语言低级绘图函数-rect
- 计算机的桌面教案,《认识计算机桌面》教案-20210608141312.pdf-原创力文档
- 班尼机器人如何代理_如何学习电商短视频拍摄剪辑
- GDC服务器主机与证书不匹配,调用web服务soap时,错误https URL主机名与客户端信任库中服务器证书上的公用名(CN)不匹配...
- python 7-10梦想的度假胜地_7-8----7-10练习
- spring 源码 找不到 taskprovider_Spring 源码阅读环境的搭建
- webbrowser 百度列表点击_百度信息流推广后台完整的实操流程!
- sqlmap 连接mysql_sqlmap从入门到精通-第三章-4-4-使用sqlmap直连MSSQL获取webshell或权限...
- python表单切换_python3 selenium自动化 frame表单嵌套的切换方法
- Java设计模式(访问者模式-迭代器模式-观察者模式-中介者模式)