为何今天才意识到代码可读性，可维护性的重要？
如果一份代码需要频繁修改，新增逻辑，及逻辑更新会不断破坏旧有逻辑。而逻辑本身又非常复杂。
这时代码可读性就非常重要了。
因为，在频繁改动的项目上，花在理解既有逻辑上的时间，可能比写代码的时间多 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 聊聊， 查看更多联系方式