文档【免费下载链接】styleguideStyle guides for Google-originated open-source projects项目地址https://gitcode.com/gh_mirrors/styleguide4/styleguide点击查看免费下载docguide/philosophy.md 是 Google 开源风格指南仓库styleguide中docguide/文档指南子项目的哲学基石它为「如何编写工程文档」确立了四条核心原则激进简化Radical simplicity、可读源文本Readable source text、最小可行文档Minimum viable documentation与更好胜过完美Better is better than perfect。本文以这份哲学文档为骨架结合 docguide/best_practices.md、docguide/style.md 与 docguide/READMEs.md 等配套文档系统讲解这套理念的每一个主张、背后的动机以及如何在 Markdown 写作与 README 维护中落地。读完你将掌握一套可直接复用的文档写作决策框架什么时候该删内容、为什么纯文本优于富文本、怎样让文档像测试一样被团队认真对待。哲学文档在仓库中的位置styleguide仓库汇集了 Google 多个开源项目的风格指南C、Python、Java、Go、JavaScript 等而docguide/子目录专门回答另一个问题这些指南以及任何工程文档本身应当如何被撰写与维护。它由四份相互关联的文档组成见 docguide/README.mddocguide/philosophy.md指导思想与价值观本文主体docguide/style.mdMarkdown 语法层面的具体风格规则docguide/best_practices.md文档维护的实操最佳实践docguide/READMEs.md针对 README.md 的专门指南。四者关系是「理念 → 规则 → 实践」的递进哲学文档定基调风格文档约束每一条 Markdown 写法的取舍最佳实践给出日常维护动作READMEs 指南则把理念落到最常见的文档类型上。哲学文档以老子的「埏埴以為器當其無有器之用」开篇——黏土经匠人之手成为陶器真正有用的却是器皿中空的部分Clay becomes pottery through craft, but its the emptiness that makes a pot useful。这一比喻直指全文核心文档的骨架与排版只是容器为读者腾出的「空」——即清晰的思路与最少的干扰——才是价值所在。原则一Radical simplicity —— 激进简化哲学文档将「激进简化」列为第一原则并给出五个相互支撑的主张可扩展性与互操作性优先于功能堆砌。规模scalability来自简单、速度与易用互操作性interoperability来自不加修饰、易于消化的内容。与其为一个文档堆满花哨特性不如让它在任何规模下都能快速被阅读和复用。更少的干扰带来更好的写作与更高效的阅读。每多一个装饰元素、多一段无关内容都是在向读者征收认知税。新特性绝不应干扰最简单的用例并且对不需要它们的用户保持不可见。这与工程中「默认路径要极简、高级能力按需启用」的设计哲学一致。这套指南为普通工程师设计——那些忙碌、只想尽快回去写代码的工程师。大型复杂文档是被允许的possible但不是主要目标not the primary focus。最小化上下文切换让人更快乐工程师应当能用他们读写代码时所用的同一套工具编辑器、命令行、纯文本查看来阅读文档而不是被迫切换进某种专用环境。简化的目标不是「内容变少」而是把注意力留给真正重要的信息。在仓库里这一原则直接约束了配套风格指南的篇幅取舍——docguide/style.md 开篇就声明Markdown 语法的选择要平衡三个目标源文本可读且可移植、语料库可长期维护、语法简单易记。这正是「简化」在语法层面的投影能少记的规则就不多记能少写的标记就不多写。原则二Readable source text —— 可读的源文本这一原则回答「用什么格式写文档」的问题主张同样鲜明纯文本不仅够用而且更优Plain text not only suffices, it is superior。Markdown 本身并非该公式的必要条件但它是当下最好、支持最广泛的选择HTML 通常不被鼓励。内容与呈现不得混为一体Content and presentation should not mingle。任何时候都应能抛开渲染器直接从源文件读取核心信息不想接触呈现层的用户永远不必接触它。可移植性与面向未来尽可能保持源文件对人类可读为「无法预想的未来集成」留出空间——任何能解析纯文本的工具未来都可能成为文档的消费者。静态优于动态但新鲜优于陈旧内容不应依赖任何特定服务器的功能因此静态内容更可靠同时文档必须持续更新因此保持新鲜同样重要。两者需要权衡而非二选一。把这条原则映射到 docguide/style.md 的具体规则上可以看到大量一脉相承的约束哲学主张风格文档中的落地规则内容与呈现分离强烈偏好标准 Markdown、避免 HTML hackStrongly prefer Markdown to HTML见 docguide/style.md源文本可读遵循 80 字符行宽约定与代码习惯对齐便于 Code Search 等工具处理见 docguide/style.md可移植、少歧义一律使用 ATX 风格标题#不用/-下划线式标题避免「---到底是 H1 还是 H2」的歧义见 docguide/style.md无需呈现层也能读代码块一律使用围栏fenced而非缩进式并显式声明语言让语法高亮器和下一个编辑者都无需猜测面向未来集成用反引号包裹伪路径、示例 URL 等文本防止被 Markdown 自动链接处理误伤值得注意的是docguide/style.md 在结尾再次回指哲学文档Every bit of HTML hacking reduces the readability and portability of our Markdown corpus——每一处 HTML 修补都在侵蚀 Markdown 语料库的可读性与可移植性进而限制与其他工具集成的价值。这正是「可读源文本」原则被反复执行的原因源文件本身才是长期资产渲染效果只是短期便利。原则三Minimum viable documentation —— 最小可行文档「最小可行文档」是哲学文档对「写多少」的回答它把文档与测试并列文档在「像测试一样被对待」时才会繁荣这原本是件必须做的杂务但一旦体会到它的长期回报就会逐渐爱上它。哲学文档在此直接指向 docguide/best_practices.md。简短实用胜过冗长详尽绝大多数用户只需要作者全部知识中很小的一部分但他们需要的是「快速且经常」地拿到它。「像测试一样对待文档」在 docguide/best_practices.md 中被展开为一套可操作的日常纪律文档像盆景要经常修剪。一小撮新鲜而准确的文档好过一大片处于各种荒废状态的松散「文档堆」。写作时要砍掉一切不必要的内容同时养成持续打磨的习惯——Docs work best when they are alive but frequently trimmed, like a bonsai tree。工程团队应像维护测试那样用心维护文档先识别真正需要的东西发布文档、API 文档、测试规范再小批量、频繁地删除冗余。文档与代码在同一 CL 中更新。代码变更的同时必须改文档这既能保持文档新鲜也是向评审者解释改动意图的好机会。一个合格的评审者至少应当坚持docstring、头文件、README.md 以及任何其他文档随 CL 一起更新。删除死文档。死文档是坏的它们误导人、拖慢进度、让工程师绝望、让团队负责人懒惰还会为「在代码库里留烂摊子」开先例。清理要点包括慢慢来文档健康是逐步积累的结果先删掉你确定是错的拿不准的暂时搁置让整个团队参与花时间快速扫描每份文档并做简单决定保留还是删除迁移时默认删除或留下落单的文档随时可以找回反复迭代。好的胜过完美的Prefer the good over the perfect。文档评审的标准不同于代码评审评审者可以也应该要求改进但作者通常有权援引「好于完美原则」让能改善文档的修改尽快提交而不是反复评审到「完美」。文档永远不会完美它会在团队逐渐明白真正需要记录什么的过程中持续变好。文档是代码的故事Documentation is the story of your code。写好代码并不止于编译通过或 100% 测试覆盖——写出计算机能理解的东西容易写出人和计算机都能理解的东西很难。Code Health 意识强的工程师应当先为人写作再为计算机写作。这引出了一条完整的文档谱系spectrum内联注释inline comments主要职责是提供代码本身无法承载的信息例如「这行代码为什么在这里」。方法与类注释method and class comments方法 API 文档header / Javadoc / docstring说明方法做什么、怎么用是代码必须如何行为的契约面向未来会使用和修改代码的程序员。它应说明参数、返回值、坑与限制、可能抛出的异常或返回的错误「为什么」的解释通常留给内联注释。写作时想得实际一点「这是一把锤子你用它来敲钉子。」类 / 模块 API 文档概述类或文件做什么并给几个简短用法示例存在多种用法有的高级、有的简单时示例尤其重要且务必先列最简单的用例。README.md为目录里的新读者提供方向并指向更详细的说明与用户指南这个目录打算放什么开发人员应该先看哪些文件其中有没有 API谁维护这个目录、去哪里了解更多对应 docguide/READMEs.md 的详细规范这套谱系说明「最小可行」不等于「少写」而是按读者需要分层供给能放进注释的一句话就不必写成长篇散文需要长期指引的内容才升级到 README 与用户指南。原则四Better is better than perfect —— 更好胜过完美最后一条原则管理的是协作节奏与心理状态渐进改进好过旷日持久的争论Incremental improvement is better than prolonged debate。对不完美的耐心与容忍让项目得以有机演化——文档先可用再在持续迭代中变好而不是在讨论中原地打转。不要舔饼干传递盘子Dont lick the cookie, pass the plate。我们正被海量潜在项目淹没只选择你真正能handle的那些把你无法handle的释放出去。这是对个人精力与注意力的清醒管理与其低质量地攥住所有文档不如高质量地维护少数几份并把其余交给更合适的维护者。这一条与前三条形成闭环简化降低起步门槛可读源文本降低维护成本最小可行降低写作负担而「更好胜过完美」保证这一切可以在团队协作中长期运转——没有人会因害怕达不到完美而停止改进也没有团队会因追求完美而陷入停滞。从哲学到实践一套可落地的文档决策清单把 philosophy.md 的四条原则与配套文档整合可以得到一份可直接用于日常工作的核对清单动笔之前Radical simplicity Minimum viable documentation这篇文档的核心读者是谁他们此刻最需要的一个信息是什么这个信息用一段注释、一段 docstring 还是 README 承载按 docguide/best_practices.md 的谱系选择层级不要越级写作。哪些内容属于「作者的全部知识」但读者用不上砍掉。新加的章节、示例、链接是否会让最简单的阅读路径变复杂若是移到附录或拆分。写作之中Readable source text只写标准 Markdown不混入 HTML除非是必须的大表格代码块用围栏并声明语言用反引号包裹会被自动链接误伤的伪路径docguide/style.md。保持 80 字符行宽链接、表格、标题、代码块可以例外。标题用 ATX 风格全文只用一个 H1子标题名称完整且唯一便于自动生成直观的锚点。行内链接使用显式路径同一目录内才用相对路径避免../式相对链接长链接用引用式链接并在首次使用后就近定义docguide/style.md。检查源文件不依赖渲染器光读源码能否看懂全文提交之后Better is better than perfect 维护纪律文档是否与代码在同一 CL 中提交是否在 CL 描述中向评审者说明了改动意图是否定期做「保留还是删除」的扫描小批量删除死文档是否允许「好的但不是完美的」版本先合入再逐步迭代写 README 时docguide/READMEs.md文件名必须是README.mdGitiles 不展示名为README的文件至少覆盖四要素这个包/库是什么、用来干什么联系谁状态是否弃用、是否面向公开发布更多信息去哪找如 overview.md、API 文档记住它是目录的落地页是多数读者遇到的第一份文件要给出方向而非倾泻全部细节。小结docguide/philosophy.md 用四句短小、决断的主张勾勒出 Google 文档写作的世界观简化到只留下真正有用的部分激进简化把内容与呈现分离、让源文件本身可读可读源文本把文档当作需要持续修剪的测试来维护最小可行文档接受不完美、用渐进改进推动协作更好胜过完美。它把「器」的比喻贯彻到底——风格指南、Markdown 语法、README 模板都只是黏土塑成的容器真正创造价值的是容器中为读者留出的「空」。这套哲学并不追求文档的数量与篇幅而是追求信息以最低成本抵达需要它的人。在 styleguide 仓库中继续深入若想了解语法层面的完整规则阅读 docguide/style.md想获得文档维护的操作细则阅读 docguide/best_practices.md想掌握 README 的写法阅读 docguide/READMEs.md各语言风格指南的入口与索引见根目录 README.md。赞分享文档【免费下载链接】styleguideStyle guides for Google-originated open-source projects项目地址https://gitcode.com/gh_mirrors/styleguide4/styleguide点击查看免费下载相关推荐Google styleguide 文档哲学以 Radical Simplicity 与可读源文本为核心的工程化写作指南Google styleguide 文档哲学以 Radical Simplicity 与可读源文本为核心的工程化写作指南 本文解读 Google Style文档代码质量教程Google styleguide 文档最佳实践六个原则打造小而活的工程文档Google styleguide 文档最佳实践六个原则打造小而活的工程文档 导读 本文以 Google styleguide https://link.gi文档代码质量教程模块标题模块标题 概述 模块核心功能简介不超过300字 工作原理 模块实现机制可包含流程图 使用指南 分步骤操作说明每个步骤不超过50字 配置选项 | 参数名 |开发工具CLI上一篇C3D-tensorflow微调策略大比拼全量微调VS冻结卷积层谁更准下一篇如何快速上手 ShardsCrystal 项目依赖管理的 5 个核心技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考