---

前言

学习框架以来，虽然代码量，耦合度大大减少，但是框架都有轻代码，重配置的特点，导致各种配置纷繁复杂，就算使用了注解开发，前后端互相传递数据，接收参数，也容易让初学者搞混。

如果你是看网上的视频自学，跟着视频写Demo，调用关系更是让人头大，很多种情况都是为了完成一个业务，传参，调用关系动不动就涉及到好几个文件，注释都不知道从哪开始写。所以笔者总结了一套比较有用的注释方法，能比较高效的注释Demo中的代码，理清业务之间的关系。而且隔较久时间，日后回看仍然能够清晰明了。

---

本文是学习方法总结，不涉及任何技术和代码讨论。但是不管是什么语言，什么技术都可以通过这种方法加代码注释，屡试不爽。

一、编写Readme.md

在每一个模块里面至少新建一个Readme.md文件（文件名可以自己起，叫dog.md都行），到模块的根目录。这个Readme.md可以总结一下这个Demo/项目到底是干什么的，用到的知识点，技术点是什么。

日后如果回看代码，先去找这个Readme.md, 就大概知道这个模块究竟干了什么事情了。非常方便。

下面举个例子，看我在Readme.md里面究竟写了啥：

这个Demo是我好几个月前写的了，但是今天打开Readme.md一看，感觉一目了然，很快的回忆起来了相关的知识点。

二、科学编写注释

前文中说过，写复杂Demo的注释是一件让人头大的事情，很多种情况都是为了完成一个业务，传参，调用关系动不动就涉及到好几个文件，注释都不知道从哪开始写。

经过多次总结，优化，笔者发现了一种方法。

经过分析可知，绝大多数的业务代码都可以被拆分成三部分，分别是：

• 需求(应用场景)
• 关联文件(为解决这一个业务需求，需要调用的文件们)
• 解决方案

分析完毕，下面逐条介绍究竟该怎么做

第一步：在注释中编写需求(应用场景)

需求（应用场景）的意思是： 为什么要写这些代码啊？折腾来折腾去是为了什么？这个技术应用的是哪些场景？

那么我们开始写注释，也就可以从这里写起了。先用一两句话，言简意赅地说明需求。

第二步：在注释中编写关联文件

举个例子：

现在我们要完成一个业务，需求是：在侧边栏中, 谁被选中,谁就高亮。

要完成这件事，需要动以下这么几个文件的代码： a.html, b.html , c.java , d.properties

好，那么上述几个文件就是该需求的关联。但是我们还需要找一个地方，写下来这么个关联关系。这个地方可以是上文说的Readme.md。于是我们就可以在Readme.md中这样写 :

需求(应用场景) : 在侧边栏中, 谁被选中,谁就高亮.

关联文件 : a.html , b.html , c.java , d.properties
在以上四个文件中，Ctrl+F 搜索主键：高亮侧边栏。

上面提到了主键，这里我借用了数据库的主键概念做类比。如果你的a.html , b.html , c.java , d.properties 这四个文件有成百上千行，你想迅速在这4个关联文件中找到和该需求相关的地方，效率是非常低下的。所以我就定义了这么一个主键的概念，方便快速在关联文件中搜索与该业务相关的代码。

主键最好定义成言简意赅的短语，或者英语单词。将主键放在关联文件中与该业务相关的代码附近，如果你想找到它，那就Ctrl+F，搜索主键，就能快速定位。

刚才这个例子的主键，我就叫中文：高亮侧边栏。只要能快速搜索到就行

第三步：在注释中编写解决方案

第三步是最简单的，也是大家都会做的。无非就是写注释或者伪代码，这个地方怎么做？怎么实现？这个代码什么意思？

解决方案部分，可以写在Readme.md里，也可以注释在各个关联文件的主键下面。建议写在各个关联文件中。就和平时在代码上面加注释一样，比较方便，没有特殊要求。在相关文件中搜索主键立刻就能看到旁边的注释，非常方便。

总结

我自己用了该方法加注释，学习，分析完调用关系之后，感觉思路清晰了不少，也能减轻看陈年代码看不懂的问题。大家都知道，将来找工作写业务代码的时候，Demo到用时方知少的道理。但是你如果连你平日自己写的Demo注释都看不懂，那不就凉凉了。

学习方法的总结，不止这一篇。我是一个文科生，自学编程以来，不停的踩坑，记录，总结，现在觉得高中时学的哲学还是有效的。运用科学的方法论可以帮我们理清思路，提高学习工作效率。