读《Software Engineering at Google》（10）

🤔☕️🤔☕️🤔

• 读《Software Engineering at Google》（10）—— Documentation

• 📖：@Google：关于文档的最成功经验，就是怎么对待文档就怎么对待代码，或者说怎么对待代码就怎么对待文档（🤔：书上是后面半句，但是我觉得，前面半句更有价值，文档在先还是代码在线，不是个顺序问题，而是个鄙视链问题）。所有非代码形式，需要补充说明的内容，在谷歌都叫“文档”（🤔：这个概念的放宽，瞬间让文档填满代码无法表达的每个角落。文档不是豆腐干，有固定形状只能那个样子，文档是豆浆，代码无法弥补的缝隙，都可以倒入豆浆去塞满每个缝隙）。

  🤔：写文档，听到就头疼，找文档，找不到更头疼，找到后，翻来覆去看不懂，更是痛炸了头，最后又硬撑着看代码，心里还惦记着文档，嘴里嘀咕不停，为何？代码是让机器跑，文档是让人看。说白了就是，代码，只要机器能跑就行，文档，却要人能看懂。可是，为何我们却在强调代码要可读性，而文档却持续在被弱化。冷不丁还冒出个活文档，好像以前的文档都死光了一般。为何本该写给人看的文档，让人又期盼又嫌弃，但是心里又一直割舍不下，矛盾点的焦点，到底在哪里？假设文档里全是文字，啥感觉？必定是，比最难看的代码，还难看的感觉。再假设文档里配图，有哪些对象，它们的谁依赖谁，它们如何排排队，等着事件来了轮番上阵协作完成，啥感觉？忍不住感慨到，一图胜千言。为何？代码和文字，前者是执行路线，后者是阅读路线，都是线性的阅读过程。图片看上去，上下关系、左右顺序，一目了然，它在纸面是二维，在脑子里呈现更高更复杂的维度。典型感觉到看图啥都秒懂，但是真要再说出来，啰里八嗦也不容易说清楚，别说写成文字的稿件，更别说带着逻辑判断的代码，完全无法在瞬间呈现大脑清晰易懂的画面感。毕竟我们老祖先，他们是面对着湛蓝的天空发呆时最有灵感，而不是非得等到天边飘来几个字，才浮上心头。如此这般，这般如此嘛，我不太确信，但似乎有点道理。

• 📖：文档能回答：为啥这么决定？为啥我和我们这么写代码？

  🤔：代码，能告诉我“How”，文档，能告诉我“Why”，对，没错，就是这个理。看代码，疑惑为啥这样，赶紧找文档，读文档，琢磨到底怎样，赶紧翻代码。这么说来，不写文档，可能有两方面原因。一方面，先干了再说，后面就懒得去思考和记录为啥这么干。另一方面，认识不到记录下为何的重要性，总以为不就行了嘛，何必再花费额外精力去记录。实际上，当出现人员流动时，后来人面临一堆 How，无法得知 Why 的真相，只会萌生出更多困惑和不解，由此不屑感也跟着滋生出来，到后来就时完全的不靠谱感。

    —— By 术子米德 @2022.04.18