最近在看组里的一个祖传项目框架，我觉得每个做系统的 LAB 都会有那么一两个在某年横空出世的天才少年，凭借一己之力写下一个自己用上去非常爽的框架，帮助他顺利毕业。但是，我在用这个框架的时候就遇到了非常多的问题，虽然框架功能上足够的强，但是对于我这个后来人，并没有太大的帮助。我几乎花费了一整周的时间在这上面，但还没有完全掌握所有的流程。根据 Git 的提交历史来看，这个框架前前后后写了可能有两年时间，这位前辈也用这个框架发了一片顶会（23333），但是从 Git 上看，这个 7 w行纯 C 语言的代码都是他一个人写完的，这代表着他很多的数据结构，功能和流程都是在他经过梳理之后，变得非常的通用。但这些通用的数据结构和函数往往意味着抽象，如果没有相应的文档，那么后来人很可能陷入完全看不懂的境地。我就是面临了这样的困扰。
我想具体的说说我面临的问题以及我是如何试图去解决他们的。
所有的数据结构都缺乏必要的逻辑上的说明。尽管有的数据结构都只进行了字面可读的命名，例如 chunk，recipe，但是对于里面的具体信息，就缺少注释，常常让人一头雾水。同时在使用一些常见的数据结构的时候，例如 Hash 表，由于 C 语言指针的通用，在没有对 Hash 表写明 KV 结构的时候，很难读懂 key-value 的具体逻辑含义的。没有办法，我只能看什么时候插入信息，什么时候查询 key ，拿 value 去做了什么，对比实际逻辑去看他的对应的 K-V 信息。所以，任何的数据结构都应该注明基本逻辑上的含义。
日志打印的问题。在打印日志的时候，他确实打印出了相应的信息，但是，他忽略了最重要的一点，他没有打印出函数调用，也就是说，我并不知道这个日志对应的函数调用在哪。对于我这个后来者，甚至找不到合适的位置。我不太清除C语言能不能实现获取调用函数的功能，但这也提醒我们，日志打印的时候，不能只是为了方便调试，只打印需要的信息，而忽视了我们默认的，潜在知道的，但是对于新上手的人不清楚的信息。对于日志打印，应把需要的所有信息都打印出来，而不是只打印出你关心的信息。
函数复用的问题。C语言缺乏面向对象的方法重载，重写。所以，他采用了函数指针的方法，一会这个函数指向一个具体实现的函数，而接下来，由指向了其他实现的函数。虽然这样在逻辑上进一步的抽象，但是函数的高度复用，代表着通用的数据结构，甚至出现了 void* (* func( void*, void*))，这种非常，非常，非常通用的函数签名。确实，这样方便了函数指针指来指去，但是对于后来人而言，经常需要满大街找这个函数到哪去了，甚至有的时候需要单步 debug 来看具体的变化。
缺乏一个提纲挈领的整体流程说明。他采用了多线程来加速整个系统，但是他没有对整个流程进行说明，这导致了我在后期新实现自己的方法的时候，误以为之前都有时序上的一致，然后导致自己的设计出现了严重的失误。没有整体上的流程说明，虽然自己可以做到对程序何时何状态的理解，但是对于后来人而言，常常找不到对应的时机。
在新上手一个不是非常熟悉的框架的时候，我对他们的经验就是先看对应的数据结构，通过数据结构，你至少可以了解基本的数据，这些数据往往代表着业务需要的信息，也就表示了业务需要的数据。然后尽可能对着代码，用一个实例跟着走一遍，有的时候，虽然跟不上，这时候可以利用 Debug 的形式，针对不同的数据做到流程上的了解。但是这可能会陷于细节而忽视了整体的设计。如果对一些通用的数据类型不是很了解的话，可以在 Debug 的时候，在进行查看，看具体的场景下，这个通用的数据类型是什么样的，虽然可能会仅仅着眼于某些情况，忽视了没有尝试到的场景，但是也对于理解数据类型有一定的帮助。