写点什么

读《Software Engineering at Google》(10)

作者:术子米德
  • 2022 年 4 月 18 日
  • 本文字数:1060 字

    阅读完需:约 3 分钟

🤔☕️🤔☕️🤔

  • 读《Software Engineering at Google》(10)—— Documentation

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

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

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

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

    —— By 术子米德 @2022.04.18

发布于: 刚刚阅读数: 2
用户头像

术子米德

关注

遇见每天的自己,莫忘初心,莫丢念头 2020.03.05 加入

喜欢有的没的,喜欢自言自语式笔记

评论

发布
暂无评论
读《Software Engineering at Google》(10)_架构师成长笔记_术子米德_InfoQ写作平台