Carbon 语言设计文档风格指南结构与链接规范实战解析【免费下载链接】carbon-langCarbon Languages main repository: documents, design, implementation, and related tools. (NOTE: Carbon Language is experimental; see README)项目地址: https://gitcode.com/GitHub_Trending/ca/carbon-lang导读本文基于 docs/project/design_style_guide.md 编写系统讲解 Carbon 语言项目docs/design目录下设计文档的写作规范包括统一的文档结构Overview / Alternatives considered / References 等章节、Issue 与 Proposal 的链接规则、以及对 Markdown 与 Google Docs 的通用风格要求。读完本文你将掌握如何撰写符合 Carbon 项目规范的、可被rumdl格式化工具自动校验的设计文档并能正确组织代码块、引用源码与 Proposal 链接使文档在 GitHub 上可读、可检索、可追溯。背景为什么 Carbon 需要一份设计风格指南Carbon 是一个实验性语言项目其设计文档体系庞大见 docs/design/README.md内容横跨类型系统、泛型、模式匹配、C 互操作等数十个主题。为了让这些文档看起来像出自同一位作者之手design_style_guide.md定义了语言设计文档在结构、风格与格式上的约定。要点如下适用范围docs/design目录下的所有语言设计文档核心目标一致性consistent style and tone让读者在浏览不同设计文档时获得统一的阅读体验上位规范设计文档遵循 CONTRIBUTING.md 中约定的 Carbon 文档风格约定即 Google 开发者文档风格指南 rumdl格式化工具。需要强调的是该指南不是写给最终用户的编程手册而是写给语言设计者与贡献者的写作规范——它决定了一个设计决策应该以什么结构、什么语气、什么链接方式写进文档。通用风格约定General设计文档的通用风格由 CONTRIBUTING.md#google-docs-and-markdown 统一约定主要包括遵循 Google 开发者文档风格指南包括用词、语态、标题层级等Markdown 文件统一使用rumdl格式化并通过prek自动化执行详见 docs/project/contribution_tools.md#running-prek连字符约定不采用 Google 风格指南推荐的破折号text—text而使用两侧带空格的双连字符text -- text因为社区成员经常在等宽字体下阅读 Markdown此时破折号不易辨识人物称谓统一使用 developers 指代编写 Carbon 代码的人群以覆盖软件开发者、系统工程师、数据科学家等多种称谓许可证头所有 Markdown 文件顶部必须带有 Apache-2.0 WITH LLVM-exception 许可证注释块见CONTRIBUTING.md#license。例如docs/design/assignment.md的顶部即为标准格式# Assignment !-- Part of the Carbon Language project, under the Apache License v2.0 with LLVM Exceptions. See /LICENSE for license information. SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception --这一头部同样出现在docs/design/README.md、docs/project/README.md 等所有项目文档中是文档可追溯、可引用的基础。链接规范Linking链接是设计文档中最容易出现混乱的部分指南对此给出了两条明确的规则1. Issue / 完整 Proposal 的链接指向 GitHub Issue 或已完成完整的 Proposal时使用文本#nnnnnnnn为 Issue 或 PR 编号可可选地附带 Proposal 标题链接目标为 GitHub 上的 Issue 或 Pull Request。[#123: widget painting](https://github.com/carbon-language/carbon-lang/pull/123)2. Proposal 具体章节的链接指向 Proposal特定章节时应链接到仓库中的 Proposal 文件副本链接文本使用章节标题或其他合适的文字。Painting details仓库中的实际应用在docs/design的正文中这两类链接被大量使用。例如 docs/design/README.md 引用提案 - Proposal [#2360: Types are values of type type](https://github.com/carbon-language/carbon-lang/pull/2360)而 docs/design/assignment.md 的Alternatives considered节引用仓库内文件- [Design choices for compound assignment](https://link.gitcode.com/i/9b4fe66294f37c6547bd991aea868aaa)提示Issue/PR 编号使用#前缀、提案文件名使用p前缀加五位数编号如p002511这是阅读和撰写文档时快速区分两类链接的实用经验。文档结构规范Document structure设计文档通常应划分为以下level-two##章节章节是否必选作用Table of contents必选自动生成目录由 toc 注释块自动维护TODO可选标记未完成的设计点Overview必选概述设计的高层概念若干详细设计章节视需要深入描述设计细节Alternatives considered必选列出曾被考虑但被否决的备选方案References必选链接外部背景资料与相关 ProposalOverview 与详细设计章节Overview遵循BLUFBottom Line Up Front结论先行原则先描述该设计领域的高层概念。若 Overview 无法完全覆盖详细设计可按需增加更多章节。详细设计章节的目标是回答四个问题已经做出了哪些设计选择这些选择如何融入 Carbon 的整体设计这些选择的理由是什么与 Carbon 最可能被拿来比较的语言尤其是C、Rust、Swift相比这些选择为何不同、如何不同Alternatives considered本节以**要点列表bullet points**形式简要描述曾被考虑过的备选设计并引用讨论过这些设计的 Proposal- Paint widgets from bottom to top。仓库实例docs/design中几乎所有主题文档都包含该节。例如 docs/design/tuples.md 的Alternatives considered节记录了空元组单元素元组尾逗号等备选方案及其取舍docs/design/README.md 中关于array(T, N)的章节也列出了[T; N] builtin syntax、array [T; N] builtin syntax等多种被否决的语法备选详见README.md#L896-L901。References本节以要点列表形式提供以下链接提供背景信息或补充资料的外部文档为本文档所述设计做出贡献的每一个 Proposal。示例- [Wikipedia example page](https://en.wikipedia.org/wiki/Wikipedia:Example) - Proposal [#123: widget painting](https://github.com/carbon-language/carbon-lang/pull/123)。关键约定指向设计其他部分的链接应**内联inline**放在正文中而不是放进 References 节。例如docs/design各文档在正文中直接链接[Source files](https://link.gitcode.com/i/bd607b12d5dafb4c55d828db778ea9f2)、Lexical conventions等References 只负责外部资料与 Proposal 追溯。与 Proposal 模板的呼应文档结构的来源design_style_guide.md规定的文档结构与 proposals/scripts/template.md 定义的 Proposal 模板高度一致——后者同样包含 Abstract、Problem、Background、Proposal、Details、Rationale、Alternatives considered等章节并建议通过./new_proposal.py TITLE初始化新 Proposal。这说明设计文档与 Proposal 文档共享同一套先结论、后细节、再记录备选的叙事骨架设计文档的Overview对应 Proposal 的Abstract / Problem设计文档的详细设计章节对应 Proposal 的Details / Rationale两者都以Alternatives considered收束形成完整的决策记录链。从源码结构看如 proposals/scripts/check_proposal_names.py 与 proposals/scripts/utils.pyProposal 文件名必须遵循pNNNNN-标题.md的命名约定这也解释了为何设计文档中的链接文本普遍使用#nnnn编号与pNNNNN文件名。实战要点小结撰写或评审 Carbon 语言设计文档时建议按以下清单自查结构是否包含自动生成的目录、Overview、至少一个详细设计章节、Alternatives considered、ReferencesOverview 是否 BLUF读者能否在前几行就明白本设计领域的高层结论备选方案是否可追溯Alternatives considered 是否都链接到了对应的 Proposal 文件章节链接文本Issue/PR 用#nnnnProposal 章节用仓库内文件路径 #章节名相关设计链接内联外部资料放 References。风格一致性是否遵循 Google 开发者文档风格、使用text -- text双连字符、统一用 developers 指代用户、文件头部带许可证注释格式化提交前用prek运行rumdl对 Markdown 进行格式化校验。遵循这套规范既能保证 Carbon 设计文档在 docs/design 目录下的统一气质也能让每一处设计决策都有明确的 Proposal 出处方便后续语言演进如 docs/project/evolution.md 所描述的治理流程中追溯与复查。【免费下载链接】carbon-langCarbon Languages main repository: documents, design, implementation, and related tools. (NOTE: Carbon Language is experimental; see README)项目地址: https://gitcode.com/GitHub_Trending/ca/carbon-lang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Carbon 语言设计文档风格指南：结构与链接规范实战解析
Carbon 语言设计文档风格指南结构与链接规范实战解析【免费下载链接】carbon-langCarbon Languages main repository: documents, design, implementation, and related tools. (NOTE: Carbon Language is experimental; see README)项目地址: https://gitcode.com/GitHub_Trending/ca/carbon-lang导读本文基于 docs/project/design_style_guide.md 编写系统讲解 Carbon 语言项目docs/design目录下设计文档的写作规范包括统一的文档结构Overview / Alternatives considered / References 等章节、Issue 与 Proposal 的链接规则、以及对 Markdown 与 Google Docs 的通用风格要求。读完本文你将掌握如何撰写符合 Carbon 项目规范的、可被rumdl格式化工具自动校验的设计文档并能正确组织代码块、引用源码与 Proposal 链接使文档在 GitHub 上可读、可检索、可追溯。背景为什么 Carbon 需要一份设计风格指南Carbon 是一个实验性语言项目其设计文档体系庞大见 docs/design/README.md内容横跨类型系统、泛型、模式匹配、C 互操作等数十个主题。为了让这些文档看起来像出自同一位作者之手design_style_guide.md定义了语言设计文档在结构、风格与格式上的约定。要点如下适用范围docs/design目录下的所有语言设计文档核心目标一致性consistent style and tone让读者在浏览不同设计文档时获得统一的阅读体验上位规范设计文档遵循 CONTRIBUTING.md 中约定的 Carbon 文档风格约定即 Google 开发者文档风格指南 rumdl格式化工具。需要强调的是该指南不是写给最终用户的编程手册而是写给语言设计者与贡献者的写作规范——它决定了一个设计决策应该以什么结构、什么语气、什么链接方式写进文档。通用风格约定General设计文档的通用风格由 CONTRIBUTING.md#google-docs-and-markdown 统一约定主要包括遵循 Google 开发者文档风格指南包括用词、语态、标题层级等Markdown 文件统一使用rumdl格式化并通过prek自动化执行详见 docs/project/contribution_tools.md#running-prek连字符约定不采用 Google 风格指南推荐的破折号text—text而使用两侧带空格的双连字符text -- text因为社区成员经常在等宽字体下阅读 Markdown此时破折号不易辨识人物称谓统一使用 developers 指代编写 Carbon 代码的人群以覆盖软件开发者、系统工程师、数据科学家等多种称谓许可证头所有 Markdown 文件顶部必须带有 Apache-2.0 WITH LLVM-exception 许可证注释块见CONTRIBUTING.md#license。例如docs/design/assignment.md的顶部即为标准格式# Assignment !-- Part of the Carbon Language project, under the Apache License v2.0 with LLVM Exceptions. See /LICENSE for license information. SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception --这一头部同样出现在docs/design/README.md、docs/project/README.md 等所有项目文档中是文档可追溯、可引用的基础。链接规范Linking链接是设计文档中最容易出现混乱的部分指南对此给出了两条明确的规则1. Issue / 完整 Proposal 的链接指向 GitHub Issue 或已完成完整的 Proposal时使用文本#nnnnnnnn为 Issue 或 PR 编号可可选地附带 Proposal 标题链接目标为 GitHub 上的 Issue 或 Pull Request。[#123: widget painting](https://github.com/carbon-language/carbon-lang/pull/123)2. Proposal 具体章节的链接指向 Proposal特定章节时应链接到仓库中的 Proposal 文件副本链接文本使用章节标题或其他合适的文字。Painting details仓库中的实际应用在docs/design的正文中这两类链接被大量使用。例如 docs/design/README.md 引用提案 - Proposal [#2360: Types are values of type type](https://github.com/carbon-language/carbon-lang/pull/2360)而 docs/design/assignment.md 的Alternatives considered节引用仓库内文件- [Design choices for compound assignment](https://link.gitcode.com/i/9b4fe66294f37c6547bd991aea868aaa)提示Issue/PR 编号使用#前缀、提案文件名使用p前缀加五位数编号如p002511这是阅读和撰写文档时快速区分两类链接的实用经验。文档结构规范Document structure设计文档通常应划分为以下level-two##章节章节是否必选作用Table of contents必选自动生成目录由 toc 注释块自动维护TODO可选标记未完成的设计点Overview必选概述设计的高层概念若干详细设计章节视需要深入描述设计细节Alternatives considered必选列出曾被考虑但被否决的备选方案References必选链接外部背景资料与相关 ProposalOverview 与详细设计章节Overview遵循BLUFBottom Line Up Front结论先行原则先描述该设计领域的高层概念。若 Overview 无法完全覆盖详细设计可按需增加更多章节。详细设计章节的目标是回答四个问题已经做出了哪些设计选择这些选择如何融入 Carbon 的整体设计这些选择的理由是什么与 Carbon 最可能被拿来比较的语言尤其是C、Rust、Swift相比这些选择为何不同、如何不同Alternatives considered本节以**要点列表bullet points**形式简要描述曾被考虑过的备选设计并引用讨论过这些设计的 Proposal- Paint widgets from bottom to top。仓库实例docs/design中几乎所有主题文档都包含该节。例如 docs/design/tuples.md 的Alternatives considered节记录了空元组单元素元组尾逗号等备选方案及其取舍docs/design/README.md 中关于array(T, N)的章节也列出了[T; N] builtin syntax、array [T; N] builtin syntax等多种被否决的语法备选详见README.md#L896-L901。References本节以要点列表形式提供以下链接提供背景信息或补充资料的外部文档为本文档所述设计做出贡献的每一个 Proposal。示例- [Wikipedia example page](https://en.wikipedia.org/wiki/Wikipedia:Example) - Proposal [#123: widget painting](https://github.com/carbon-language/carbon-lang/pull/123)。关键约定指向设计其他部分的链接应**内联inline**放在正文中而不是放进 References 节。例如docs/design各文档在正文中直接链接[Source files](https://link.gitcode.com/i/bd607b12d5dafb4c55d828db778ea9f2)、Lexical conventions等References 只负责外部资料与 Proposal 追溯。与 Proposal 模板的呼应文档结构的来源design_style_guide.md规定的文档结构与 proposals/scripts/template.md 定义的 Proposal 模板高度一致——后者同样包含 Abstract、Problem、Background、Proposal、Details、Rationale、Alternatives considered等章节并建议通过./new_proposal.py TITLE初始化新 Proposal。这说明设计文档与 Proposal 文档共享同一套先结论、后细节、再记录备选的叙事骨架设计文档的Overview对应 Proposal 的Abstract / Problem设计文档的详细设计章节对应 Proposal 的Details / Rationale两者都以Alternatives considered收束形成完整的决策记录链。从源码结构看如 proposals/scripts/check_proposal_names.py 与 proposals/scripts/utils.pyProposal 文件名必须遵循pNNNNN-标题.md的命名约定这也解释了为何设计文档中的链接文本普遍使用#nnnn编号与pNNNNN文件名。实战要点小结撰写或评审 Carbon 语言设计文档时建议按以下清单自查结构是否包含自动生成的目录、Overview、至少一个详细设计章节、Alternatives considered、ReferencesOverview 是否 BLUF读者能否在前几行就明白本设计领域的高层结论备选方案是否可追溯Alternatives considered 是否都链接到了对应的 Proposal 文件章节链接文本Issue/PR 用#nnnnProposal 章节用仓库内文件路径 #章节名相关设计链接内联外部资料放 References。风格一致性是否遵循 Google 开发者文档风格、使用text -- text双连字符、统一用 developers 指代用户、文件头部带许可证注释格式化提交前用prek运行rumdl对 Markdown 进行格式化校验。遵循这套规范既能保证 Carbon 设计文档在 docs/design 目录下的统一气质也能让每一处设计决策都有明确的 Proposal 出处方便后续语言演进如 docs/project/evolution.md 所描述的治理流程中追溯与复查。【免费下载链接】carbon-langCarbon Languages main repository: documents, design, implementation, and related tools. (NOTE: Carbon Language is experimental; see README)项目地址: https://gitcode.com/GitHub_Trending/ca/carbon-lang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考