腾讯软件工程师是怎样写设计软件包的？

对之前提该系统的平均明白层面更低，也就意味着结构设计软体包经常之前提：

越发详细的中华文化背景解说。 更较少用到内部术语或首字母。 更多详述结构设计基本概念、选材，更较少解释具体充分利用内容。

其次，考虑到读者群最喜欢如何读物？大则有读者群不才会逐字逐句读物你的结构设计软体包。大家都很有事，上才会只才会扫描大体结构，然后读物（或者跳读）自己感兴趣的则有。读者群最喜欢“主人翁”。将副标题以主人翁的结构呈现最容不免被放弃，即使我们并不是之前提主人翁一个传统的打怪替换的主人翁。虽然主人翁副标题各有各不相同，但大则有主人翁都遵循一些基本的范式。例如， 约瑟夫·坎伯总结提出全全球大则有神话主人翁都符合 “英雄之旅” --- “启程、启蒙、归程”三幕 --- 这个模式。

对于结构设计软体包 / 科技博士论文写成作，通用公共安全的同样是 Writing Science 所解说的 OCAR 主人翁结构。

Opening：开场，中华文化背景解说 Challenge：单打独斗，所要补救的疑问 Action：联合行动，执行的实验室 / 结构设计 /... Resolution：结果

结构设计软体包上才会遵循特定的有组织结构，我们可以将每一个结构对应以到 OCAR 的各不相同则有，以此主人翁主人翁。

最后，辩证看待结构设计软体包一致病态。结构设计软体包一致病态 vs. 字符一致病态都称作一致病态，两者有些之外之处：

软体包特别强调强调的副标题某种层面是并非显而不免听闻的事项： 未仅仅的恰当无误：未完美的字符，也未完美的结构设计软体包。 各不相同的读者群对一致病态的阐释有更深的各不相同， 一致病态是主观的。 在方法论之中，我们追求让更多（而非所有）读者群更顺畅地读物结构设计软体包。 免得为完美主义代价太重字符。平衡状态一致病态与等待时间效率。 我们的之前提是有意识地提很低软体包写成作 / 字符高水平。很低质量的写成作是一种习惯。提很低高水平的方法有： 多读他人优秀的结构设计软体包。 评审团（Design doc review/Code review）有益于。 结构设计软体包评审团经常主要关注该系统结构设计不合理病态，但是一致病态总体的评审团也有适当。 多写成作、多重写、多重构成。

3.2 结构设计软体包的基本原则

在想到结构设计软体包撰写成的三个之前提后，就才会进入软体包的编撰成收尾。结构设计软体包是非正式的软体包，因此他们的副标题不才会遵循严格的准则，一个首要原则是，针对项借以具体原因可以用相比较不合理的方式将来编撰成。尽管如此，笔者也的有资料并为典范自身长处假定一些建议。

写成作情调的三要素

结构设计软体包的写成作也是该系统设计写成作（Technical Writing），因此同样强调此表三要素：

明晰 简洁 华丽

结构设计软体包的五个这两项

该系统结构设计及编撰成结构设计软体包时之前提特别注意的 5 个这两项。

任何架构疑问都是选材。

在软体结构设计之中，未任何一个也就是说有仅仅意思上的优劣。每一个结构设计决定都之前提顾虑到很多相无视的因素。例如，可扩展到病态和高效率相背；一直高效率和细期收益相背；冲击力也化增加了高效率，但减较少了灵活病态。“很低内聚低极化” 便于迭代，但是才会增加细期的开发新效率。NoSQL 比 SQL 病态能很低，但代价是功能的大幅减较少。

2. “为什么” 比 “怎么动手” 更不可忽视。

结构设计所补救的疑问经常是比较简单而模糊的，因此，补救补救方案经常是不唯一的。对工程结构设计，补救方案的论证上才会比补救方案本身更不可忽视。

3. 考虑到等待时间也就是说

动手结构设计选材时不能或许等待时间也就是说，只结构设计某个收尾的终态。结构设计之前提考虑到此表总体：

可维护病态与可扩展到病态考虑到 充分利用逆时针 考虑到将来构想

4. 防止过度结构设计

结构设计此之前，界定疑问的范围内。一个较差界定的疑问是一个较差结构设计的适当条件。

免得恶习结构设计模型式、结构MVC、XX 驱动结构设计，这些是用以，而非法则；免得为了制造疑问而补救疑问；免得通过比较简单的结构设计来说明了文书工作的难度和高度: 一个困难的疑问也许才会有一个单纯的无误；也免得过分担忧结构设计被迅速淘汰。延续可扩展到病态，但免得在未知时耗费心力扩展到。

5. 总结

最不可忽视的是要知道如何结构设计，知道自己在结构设计什么。邓宁·克鲁格效应以告诉我们，这未必显然。

I think test-driven design is great. I do that a lot more than I used to do. But you can test all you want and if you don’t know how to approach the problem, you’re not going to get a solution.

- Coders at Work, Peter Norvig

3.3 结构设计软体包的最佳方法论

遣词

用词要简练、直观、直白。

恰当用到专业术语。 不合理地用到常听闻术语可以减较少互动效率。 免得太多用到过分小众或新创的术语。 适当时提均需比对的英文术语以方便阐释。 防止无正则理解式的缩略词。 去掉层面状语。 不管所写成意左图为何， “极为不可忽视” 和 “不可忽视” 在读者群看来有别于。 用到信息。 与其完全一致指出“该该系统的病态能增加相比较来说”，不如“该该系统的病态能增加了 42%”更为可信，也更方便读者群动手到自己的判断。 忌佶屈聱牙。 例如上文，应以改为“免得用到过分生僻的字汇，免得过度用到书面语”。 千万免得写成文言文。

造句

用到细句，免得用到多细语的比较简单句式。 读者群不是来考 GRE 的。 写成软体包也不是为了炫耀自己可以驾驭长难句。

“该系统形式疑问就是后面这样一个疑问：怎样把各种各不相同的都可各种各种类型顾及在一个该系统之中，以使较很低的都可各种各种类型总是从较低的都可各种各种类型本体出来，也就是说之前者可还原为后者。为明白决这个疑问，我们必须从其相互可还原病态来研究各种各不相同的都可各种各种类型。为此借以，我们要根据所涉及的都可领域的单单科学常识为每一个要考察的都可寻找其基本似乎普遍存在的充分而适当的条件的各种也许病态。辩解我们可实行后面的办法来展开，即敦促这门单单科学假定基本似乎的一个（似乎而常在的）表征。”

Excerpt From: 【德】鲁道夫·卡尔纳普. “全球的命题本体.”

单纯理解，去掉无意思的修饰，去掉借此缓和语调的细语。 假定：“我们可以注意到， TencentDB 在一定层面上可以满足我们对职责背书的需要。 ”重写后：“TencentDB 背书职责”。 假定：“MR 提恳请文档作为读者群查到重写近现代时第一等待时间注意到的文档，其不可忽视病态不言而喻。 ”重写后：“读者群查到重写近现代时才会首先关注 MR 提恳请文档。” 本段谈论另一个疑问，即… 语调要冷静。防止过分口语化。 免得加背影 免得用到语调词 免得用到叹号！如果希望强调，用到 粗体 或者 斜线 ！也可以用到国际标准结尾！ 直观。完全一致指出了客观似乎，防止投身于主观歇斯底里。

之前半部

之前半部某种层面须要细。上才会，一个之前半部免得超过 8 个明晰的文法。每个之前半部有且非常少一个明晰的隐喻。每个之前半部开头某种层面是隐喻句，方便读者群加速明白之前半部一句话。之前半部之中的每说道某种层面与隐喻紧密就其；否则，它某种层面另起之前半部，或者某种层面删掉。

特别注意之前半部的流动。之前半部文法某种层面始于一个读者群已经陌生的观念，将属于自己副标题安放文法结尾。这样，读者群可以更衔接地阐释。

用到沙罗

用到 Bullet point 标明无顺序的沙罗，用到数字序号完全一致之前后顺序。如何恰当用到沙罗不在本文详细展开，才会在全面性文章解说（如果有全面性的话），也可参听闻；也的的有资料。

结构

用到COM：用到COM可以作为探究依靠于，同时也提均需了相比较较明晰且约束的结构。；也提均需了一份结构设计软体包COM以均需参考。

用到左图表：一左图胜千言。不合理地用到左图表可以巨大地减较少用户的阐释效率。

用到结尾：结尾要国际标准、要简细明晰

篇幅

结构设计软体包免得过长。太多副标题堆积在一个软体包之中才会让读者群丧失兴趣。

对于一个大型式单项来说，10 页（~5000 字）左右是一个更好的总长度。当超过这个总长度时，可以考虑到将疑问拆细分子疑问分别编撰成结构设计软体包，并在总体结构设计软体包之中镜像子结构设计软体包。

对于小疑问动手增量的改进，考虑到用到单页软体包 (one-pager)。上才会这类软体包的范围内较小，补救疑问较单纯，之前提用户群体仅限于对疑问已经有充分明白的内部成员。这时，可以去掉中华文化背景等副标题，而仅用到 之前提 --- 补救方案 单发论证的结构。

排版

用到分立的字体。用户不才会意识到各不相同的字体代表各不相同的意思，只才会感受到混乱。微软雅黑是公共安全同样。

免得用到各不相同紫色来区分副标题。免得在文之中用到超过三种紫色。可以在结尾及国际标准结尾用到标志病态的紫色，同时正文用到黑色。

附录：结构设计软体包COM

结构设计软体包未定式。即使如此，笔者参考谷歌结构设计软体包的结构和格式，并为典范单单文书工作长处加以完备。在此提均需一个可均需新手参考的结构设计软体包模版，您可以用到此软体包COM作为探究的典范。上才会，并不需要事无巨细地填写成每一则有，不就其的副标题这样一来略过只需。

之前提

“我们要补救什么疑问？”

用几句话完全一致指出该结构设计软体包的决定性借以，让读者群之前提一眼得知自己是不是对该结构设计软体包感兴趣。

如：“本文完全一致指出了 Spanner 的顶层结构设计"

继而，用到 Bullet Points 完全一致指出了该结构设计借此达到的不可忽视之前提，如：

可扩展到病态 多版本 全球分布 同步复制

非之前提也也许很不可忽视。非之前提并非单纯之前提的否定形式，也不是与补救疑问所谓的其它之前提，而是一些也许是读者群非意味著的、本可作为之前提但并未的之前提，如：

很低可用病态 很低可靠病态

如果也许，解释是基于哪些总体的考虑到将之作为非之前提。如：

可维护病态：本客户服务只是过渡补救方案，预计寿命三个月，待 XX 上线列车运行后只需下线

结构设计不是借此达到完美，而是借此达到平衡状态。显式地声明哪些是之前提，哪些是非之前提，适度努力读者群阐释下文之中结构设计执行者的不合理病态，同时也适度在此之后迭代结构设计时，核对在此之前的假设是不是仍然创建。

中华文化背景

“我们为什么要补救这个疑问？”

为结构设计软体包的之前提读者群提均需阐释详细结构设计所需的中华文化背景文档。按读者群范围内来提均需中华文化背景。听闻上文关于之前提读者群的圈定。 结构设计软体包某种层面是“就其的”（self-contained），即某种层面为读者群提均需足够的中华文化背景常识，使其无需有十分困难的查到资料只需阐释后文的结构设计。 保持一致简洁，上才会以几段为宜，每段简述解说只需。如果之前提向读者群提均需有十分困难的文档，最难只提均需镜像。警惕常识的诅咒（常识的诅咒（Curse of knowledge）是一种感知恰当，指人在与他人国际交流的时候，下意识地假设对方握有阐释国际交流隐喻所之前提的中华文化背景常识）。

中华文化背景上才会可以有数：

需要动机以及也许的例子。如，“（tRPC) 微客户服务模式正在子公司内更加流行，但是缺较少一个通用的、封装了常用内部用以及客户服务接口的微客户服务开放性”。 这是安放需要软体包的镜像的好地方。 此之前的版本以及它们的疑问。如，“(tRPC) Taf 是之后的应以用开放性， 有此表表现形式，…………， 但是有此表局限病态及近现代遗留疑问”。 其它非常少补救方案， 如子公司内其它补救方案或GNU补救方案， "tRPC v.s. gRPC v.s. Arvo" 就其的单项，如 "tRPC 开放性之中也许才会对接的其它 PCG 该系统"

免得在中华文化背景之中写成你的结构设计，或对疑问的补救基本概念。

总体结构设计

“我们如何补救这个疑问？”

用一页完全一致指出了很低层结构设计。完全一致指出该系统的主要组合而成则有，以及一些决定性结构设计执行者。某种层面完全一致指出该该系统的模块化和执行者如何满足之前文所列出的之前提。

本结构设计软体包的评审团人某种层面之前提根据该总体结构设计阐释你的结构设计基本概念并动手到评论者。完全一致指出了某种层面对一个新投身于的、不在该单项文书工作的腾讯机械师而言是可以阐释的。

录用用到 该系统关联左图 完全一致指出了结构设计。它可以使读者群明晰地明白文之中的新该系统和已经陌生的该系统间的关联，也可以构成新该系统内部简述的组合而成模块化。

特别注意：免得只放一个左图而不动手任何完全一致指出，恳请根据里面段落的敦促用文字完全一致指出了结构设计观点。

一个示例该系统关联左图

自举的软体包结构左图

也许不太好的顶层结构设计

免得在这里完全一致指出了内容，安放下一副标题之中；免得在这里完全一致指出了中华文化背景，安放上一副标题之中。

详细结构设计

在这一节之中，除了解说结构设计补救方案的内容，还某种层面有数在产生之后补救方案现实生活之中，主要的结构设计观点及折中（tradeoff）。这一节的结构和副标题因结构设计都可（该系统，API，流程等）的各不相同可以自由决定，可以区分一些段落来更好地有组织副标题，尽也许以简洁明了的结构阐明整个结构设计。

免得太多写成充分利用内容。就像我们不录用添加只是完全一致指出"字符动手了什么"的注释，我们也不录用在结构设计软体包之中只完全一致指出你具体要怎么充分利用该该系统。否则，为什么不这样一来充分利用呢？

此表副标题也许是充分利用内容例子，不适合在结构设计软体包之中谈论：

API 的所有内容 存储器该系统的 Data Schema 具体字符或假字符 该该系统各模块化字符的存放方位、各模块化字符的布局 该该系统用到的编译器版本 开发新约束

上才会可以构成此表副标题（特别注意，段落的命名可以更改为更明晰说明了副标题的结尾）：

各子模块化的结构设计

阐明一些比较简单模块化内部的内容，可以构成一些模块化左图、流程左图来努力读者群阐释。可以依靠时序左图展开展现，如一次加载在各子模块化之中的列车运行现实生活。每个子模块化之前提完全一致指出自己普遍存在的意思。如无适当，惟恐添模块化。如果未特殊原因（例如该结构设计软体包是为了完全一致指出了并充分利用一个基本算法），免得在该系统结构设计投身于字符或者假字符。

API 接口

如果结构设计的该系统才会曝露 API 接口，那么简述地完全一致指出了一下 API 才会努力读者群阐释该系统的边界。防止将整个接口复制粘贴到软体包之中，因为在特定编程语言之中的接口上才会构成一些语言内容而显得冗长，并且有一些内容也才会很快变化。特别强调表现 API 接口跟结构设计最就其的主要则有只需。

存储器

解说该系统依靠的存储器结构设计。该则有副标题某种层面问此表疑问，如果无误并非显而不免听闻：

该该系统对信息 / 存储器有哪些敦促？ 该该系统才会如何用到信息？ 信息是什么各种类型式的？ 信息冲击力也有多大？ 读取成比是多较少？读取成频率有多很低？ 对可扩展到病态是不是有敦促？ 对原子病态敦促是什么？ 对一致病态敦促是什么？是不是之前提背书职责？ 对可用病态敦促是什么？对病态能的敦促是什么？ …… 基于里面的似乎，在线某种层面如何选型式？ 除此以则有关联型式在线还是非关联型式在线？是不是有更好的之跨平台可以用到？ 如何分片？是不是之前提分库分表？ 是不是之前提副本？ 是不是之前提他处容灾？ 是不是之前提冷热转化？ …………

信息的表象以及信息间关联的完全一致指出了至关不可忽视。可以依靠 ER 左图 (Entity Relationshiop) 的方式将展现信息关联。

问上述疑问时，尽也许提均需信息，将信息作为无误或作为依靠于。免得问“信息冲击力也很大，读取成频繁”，而是问“预计信息冲击力也为 300T， 3M 日读出， 0.3M 日写成入， 巅峰 QPS 为 300”。这样才能为下一步的具体在线则有型式提均需详细的执行者依据，并让读者群信服。

特别注意：在选型式时也应以有数也许才会造成显著冲击的非该系统设计因素，如开销。

防止将所有信息定义（data schema）复制粘贴到软体包之中，因为 data schema 更偏充分利用内容。

其他补救方案

“我们为什么不用另一种方式将补救疑问？”

在解说了之后补救方案后，可以有一节解说一下结构设计现实生活之中考虑到过的其他结构设计补救方案（Alternatives Considered）、它们各自的优缺点和折中点、以及导致同样之后补救方案的原因等。上才会，有长处的读者群（偏爱是补救方案的审阅者）才会很人为地记得一些其他结构设计补救方案，如果这里的解说完全一致指出了了未同样这些补救方案的原因，就防止读者群带着疑问看明晰个结构设计再次来告诉所写成。这一节可以说明了结构设计的严谨病态和全面病态。

交叉不就其的

典范设施

如果典范设施的除此以则有之前提特殊顾虑到，则某种层面列出。

如果该该系统的充分利用之前提对典范设施展开增强或变更，也某种层面在此谈论。

可扩展到病态

你的该系统如何扩展到？交叉扩展到还是交叉扩展到？特别注意信息存储器量和每秒钟都也许才会之前提扩展到。

公共安全 & 个人文档

单项上才会之前提在结构设计期即确认对公共安全病态的适当，而难以事后补足。各不相同于其它则有是预设的，公共安全则有经常是之前提的。即使你的该系统不之前提考虑到公共安全和个人文档，也之前提显式地在本章完全一致指出为何是不适当的。公共安全病态如何适当？

该系统如何专利权、鉴权和审计 (Authorization, Authentication and Auditing, AAA）？ 是不是之前提翻墙（break-glass）机制？ 有哪些推断恶意和潜在的不公共安全依靠关联？ 是不是某种层面与专业公共安全制作组谈论公共安全病态结构设计评审团？ …… 信息明晰病态

如何适当信息明晰病态（Data Integrity）？如何挖掘出存储器信息的损坏或遗漏？如何恢复原？由在线适当只需，还是之前提额则有的公共安全采取措施？为了信息明晰病态，之前提对稳定病态、病态能、可复用病态、可维护病态造成哪些冲击？

延误

声明延误的意味著之前提。完全一致指出了意味著延误也许造成的冲击，以及就其的应以对采取措施。

冗余 & 可靠病态

是不是之前提容灾？是不是之前提短时间保护措施、正因如此冬歇期、接口熔断、轻重转化？是不是之前提备份？备份策略是什么？如何修复？在信息遗漏和恢复原错综比较简单才会再次次发生什么？

稳定病态

SLA 之前提是什么？如果监控？如何适当？

举例来说依靠

你的举例来说依靠的可靠病态（如 SLA）如何？才会对你的该系统的可靠病态造成何种冲击？如果你的举例来说依靠不宜用，才会对你的该系统造成何种冲击？除了客户服务级的依靠则有，免得忘记一些隐含的依靠，如 DNS 客户服务、等待时间协议客户服务、列车运行集群等。

充分利用构想

完全一致指出了等待时间及人力顾及（如里程碑）。这十分困难就其人员明白意味著，调整文书工作构想。

将来构想

将来也许的构想才会方便读者群更好地阐释该结构设计以及其适配。

我们似乎某种层面把结构设计限定在即便如此疑问，但是该结构设计也许是更很低层该系统所要补救疑问的一则有，或者只是收尾病态补救方案。读者群也许才会对补救方案的明晰病态有所疑问，才会批评到底疑问是不是得到明晰补救，甚至才会批评该疑问在更很低层的该系统之中是不是似乎有一点补救。“中华文化背景（过去）--- 即便如此补救方案 --- 将来构想” 三者的为典范才会为读者群提均需更好的一个大。

附录：的有资料

参考软体包

结构设计软体包

如何编撰成管理学结构设计软体包 感谢 hankzheng，本文则有中文翻译源自此文。 Design Docs at Google[COM] 结构设计软体包COM Bzlmod 结构设计提案 [示例] 视频后台组件平台 - 总体结构设计 [示例] Unionplus K-List 存储器结构设计替代补救方案 Unionplus K-List 存储器结构设计替代补救方案 chromium 结构设计软体包范例

该系统设计写成作

Google Technical Writing Course Microsoft Writing Style Guide

参考书籍

写成作 / 理解

Style, Joseph M. Williams / Joseph Bizup 金字塔方法 : 探究、写成作和补救疑问的命题, 巴巴拉·明托 写成作这回事，玛格丽特·金 The elements of style, William Strunk Jr. / E. B. White Coders at work，Peter Siebel 报道 Joshua Block 中文翻译：

Joshua Block: "Another is Elements of Style, which isn’t even a programming book. You should read it for two reasons: The first is that a large part of every software engineer’s job is writing prose. If you can’t write precise, coherent, readable specs, nobody is going to be able to use your stuff. So anything that improves your prose style is good. The second reason is that most of the ideas in that book are also applicable to programs."

精准理解，很低田贵久 写成作提很低一点点，Mary-Kate Mackey On writing well, William Zinsser Artful Sentences, Virginia Tufte

该系统设计写成作 / 文献资料写成作

写成作是门手艺，刘军强 How to write a lot, Paul J. Silvia Writing for Computer Science, Justin Zobel The craft of research, Wayne C. Booth / Gregory G. Colomb / Joseph M. Williams 才会读才才会写成， Phillip C. Shon Writing Science, Joshua Schimel

主人翁

之前文强调了要讲主人翁。此表书目详述了何谓主人翁、为什么要讲主人翁及如何讲主人翁：

Writing Science, Joshua Schimel 金字塔方法 : 探究、写成作和补救疑问的命题, 巴巴拉·明托 主人翁，Robert McKee 如何读物一本文学创作书， 托马斯·福斯特

架构结构设计

Software engineering at Google, Titus Winters / Tom Manshreck / Hyrum K. Wright Build Secure and realiable systems, Heather Adkins / Betsy Beyer / Paul Blankinship / Piotr Lewandowski / Ana Oprea / Adam Stubblefield The Design of Design, Fredrick P. Brooks Jr. Fundamentals of Software Architecture, Mark Richards / Neal Ford

左图表

Storytelling with data，Cole Nussbaumer Knaflic

沙罗

所写成解说：

marinewu : 腾讯 PCG 应以用架构平台部 开发新高效率之中心 Tech Lead,有较丰富的 API 结构设计与评审团长处，有及该系统设计软体包的写成作与评审团长处。2021 年投身于腾讯，主要全权负责 DevOps 用以体系开发新和优化。

是什么让 Redis“竟然”回击：13 年来，总有人想替 Redis 换套新架构

你究竟有多明白GNU？InfoQ《之华北地区GNU拓展研究研究 2022 》公布

一晚上累计 292 数万人紧盯 Flightradar24 网车站，航点搜索的该系统设计方法是什么？

“台湾省山西刀削面”搜索太多，腾讯地左图宕机；BOSS 直聘即将实行末位淘汰；B 车站回应以 HR 称基本用户是 Loser ｜Q 资讯

副标题录用

InfoQ 研究之中心首次公布行业统计信息—— 《之华北地区GNU拓展研究研究 2022 》，通过飞凤模型式表象了比较简单的GNU运转机制，探究GNU生态之中各不相同参与大体的价值和职能。

读物统计信息你可以明白加速如何评论者一个GNU社区的运营原因；如何加速评论者一个GNU单项优秀层面；如何评论者中小企业对GNU的功绩；统计信息也设立了公正的评估模型式，为企业执行者提均需更多参考依据。

我们在此典范上也评选了之华北地区 Top 30 GNU单项与之华北地区对GNU动手到功绩的 Top 10 中小企业。同时我们也预测了将来GNU拓展的趋势。总之， 如果你想明白GNU， 那么一定免得错过这份统计信息！

。

爱丽滴眼液和海露有什么区别
合肥哪里治疗白癜风最好
浙江早泄阳痿治疗哪家好
南京看白癜风哪个专科医院好
郑州男科医院哪家医院最好