代码整洁之道(一)最佳实践小结-阿里云开发者社区

开发者社区> 竹涧> 正文

代码整洁之道(一)最佳实践小结

简介: Any fool can write code that a computer can understand. Good programmers write code that humans can understand. 普通的工程师堆砌代码,优秀的工程师优雅代码,卓越的工程师简化代码。
+关注继续查看

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
  • 减少重复代码,提高表达力,提早构建,简单抽象

小结

作为代码整洁之道系列的第一篇,本文从注释、命名、方法,单元测试,并发等视角简单给出了一些最佳实践,下文我们会展开来从每个方面介绍更多的实践事例。相信每一个优秀的工程师都有一颗追求卓越代码的心,在代码整洁工程实践上你有哪些好的建议?数百人协作开发的代码如何保证代码整洁一致性?欢迎大家来讨论。

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

相关文章
阿里云服务器怎么设置密码?怎么停机?怎么重启服务器?
如果在创建实例时没有设置密码,或者密码丢失,您可以在控制台上重新设置实例的登录密码。本文仅描述如何在 ECS 管理控制台上修改实例登录密码。
9480 0
一些通过SAP ABAP代码审查得出的ABAP编程最佳实践
1. 这两个IF ELSE分支里检测的条件其实逻辑上来说都是同一类,应该合并到一个IF分支里进行检查: It is an expensive operation to open a file in application server with 50MB file size.
1198 0
代码审查的必要性和最佳实践
代码审查的必要性和最佳实践
1265 0
代码整洁之道(一)最佳实践小结
Any fool can write code that a computer can understand. Good programmers write code that humans can understand. 普通的工程师堆砌代码,优秀的工程师优雅代码,卓越的工程师简化代码。如何写出优雅整洁易懂的代码是一门学问,也是软件工程实践里重要的一环。前段时间通读了三本经典书籍《代码整洁之道 》、《编写可读代码的艺术》、《重构:改善既有代码的设计》,本文将重点从注释、命名、方法、异常、单元测试等方面总结了一些代码整洁最佳实践。
46 0
阿里云服务器如何登录?阿里云服务器的三种登录方法
购买阿里云ECS云服务器后如何登录?场景不同,阿里云优惠总结大概有三种登录方式: 登录到ECS云服务器控制台 在ECS云服务器控制台用户可以更改密码、更换系.
13163 0
阿里云ECS云服务器初始化设置教程方法
阿里云ECS云服务器初始化是指将云服务器系统恢复到最初状态的过程,阿里云的服务器初始化是通过更换系统盘来实现的,是免费的,阿里云百科网分享服务器初始化教程: 服务器初始化教程方法 本文的服务器初始化是指将ECS云服务器系统恢复到最初状态,服务器中的数据也会被清空,所以初始化之前一定要先备份好。
11499 0
阿里云ECS云服务器初始化设置教程方法
阿里云ECS云服务器初始化是指将云服务器系统恢复到最初状态的过程,阿里云的服务器初始化是通过更换系统盘来实现的,是免费的,阿里云百科网分享服务器初始化教程: 服务器初始化教程方法 本文的服务器初始化是指将ECS云服务器系统恢复到最初状态,服务器中的数据也会被清空,所以初始化之前一定要先备份好。
6884 0
<转> 编写超级可读代码的15个最佳实践
转自  http://blog.csdn.net/hfahe/article/details/6303585     目录(?)[-] 注释和文档 一致的排版 第一种 第二种 第三种 避免显而易见的注释 代码分组 命名的一致性 DRY原则 避免过深的嵌套 减少...
1009 0
+关注
竹涧
极简主义工程师一名,阿里云弹性计算从事研发工作,聚焦分布式系统、DevOps、SRE等领域。
16
文章
0
问答
来源圈子
更多
+ 订阅
文章排行榜
最热
最新
相关电子书
更多
《2021云上架构与运维峰会演讲合集》
立即下载
《零基础CSS入门教程》
立即下载
《零基础HTML入门教程》
立即下载