代码可读性, 开发效率与可维护性

更新日期: 2023-10-29 阅读次数: 1328 字数: 980 分类: 程序员

为何今天才意识到代码可读性,可维护性的重要?

如果一份代码需要频繁修改,新增逻辑,及逻辑更新会不断破坏旧有逻辑。而逻辑本身又非常复杂。

这时代码可读性就非常重要了。

因为,在频繁改动的项目上,花在理解既有逻辑上的时间,可能比写代码的时间多 N 倍。 提高代码可读性,可以大大降低时间成本。

反面示例

最近在维护自己写的代码时,发现前期的每一次代码规范上的偷懒,都会影响后续修改代码的效率。例如:

  • 变量名,函数名,图省事用了模棱两可的名字。
  • 超长的函数
  • 未处理的异常,错误
  • 超长的代码文件,充斥着无尽的类和函数
  • 无处不在的废弃的,但是没有清理的代码

增强代码可读性, 减少对外部文档的依赖

  • 逻辑梳理,todo 都可以放到代码注释中
  • 需要验证的放到单元测试中。

目前我的大部分文档,逻辑梳理,都放到了独立的 markdown 文档中,及 trello 项目管理工具中。 这样虽然写代码时很方便,方便跟踪,但是一旦后续要修改代码,或者增加功能,查找文档就非常麻烦。 因为,你需要先找到这段代码对应的文档在哪里,其实很难找到。 所以,最佳实际应该是把所有细节说明放到代码注释中。

项目脚手架的目录结构说明

影响自己修改代码效率的一大因素是,无法快速定位到一个功能修改对应的代码文件在哪里。

特别是项目脚手架是基于别人的代码而来,或者三方开源项目。 这些项目的目录组织要么是自己不熟悉的组织方式,要么是命名诡异,无法从名称上识别出对应的功能是什么。

比如:

  • 越来越复杂的 react 前端项目,无法分辨逻辑与组件都在哪里
  • 过度封装的 android java 项目,一个类继承个四五级,很难确定一个功能该修改哪个父类

虽然 Android Studio 这类 IDE 有 bookmark 功能,但是还是不够直观。

我觉得简单有效的做法是,在项目的 Readme.md 文件中注明目录,及关键代码文件的功能用途, 以便之后可以快速定位需要查找/改动的源文件。

以一个聊天机器人的前端 react 项目为例:

## 代码目录结构
消息处理
frontend/src/utils/rasaUtil.js

组件封装
frontend/src/compoments/card.js

如果我要增加一条消息处理规则,就可以直接找到对应的文件。

在 VIM 中更加简单,光标置于对应文件上,gf 或者 Ctrl+w gf 即可自动打开该文件。

详情参考 VIM 在 tabnew 中打开目前鼠标所在行文本所指向的文件

烟台海边的图书馆

图为烟台海边图书馆

基于 AI 的代码注释

我发现让 ChatGPT 解释一段代码的效果非常棒,一段晦涩的代码,ChatGPT 能够很好的把每行代码的作用讲解明白。

可以用来作为读代码的辅助工具。

烟台海边的图书馆

图为烟台海边图书馆

流程图

基于三方工具,或者自己实现,将代码调用逻辑自动生成流程图,然后打印出来,方便理解。

例如:

rasa 是否可以自动根据一个 intent 或者 action utter 返回涉及到的所有相关逻辑,生成流程图

微信关注我哦 👍

大象工具微信公众号

我是来自山东烟台的一名开发者,有感兴趣的话题,或者软件开发需求,欢迎加微信 zhongwei 聊聊, 查看更多联系方式