Carbon 语言设计文档风格指南：结构与链接规范实战解析-港品优选

Carbon 语言设计文档风格指南：结构与链接规范实战解析

【免费下载链接】carbon-langCarbon Language's 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时，使用文本#nnnn（nnnn为 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	必选	链接外部背景资料与相关 Proposal

Overview 与详细设计章节

Overview：遵循BLUF（Bottom Line Up Front，结论先行）原则，先描述该设计领域的高层概念。若 Overview 无法完全覆盖详细设计，可按需增加更多章节。
详细设计章节的目标是回答四个问题：
1. 已经做出了哪些设计选择？
2. 这些选择如何融入 Carbon 的整体设计？
3. 这些选择的理由是什么？
4. 与 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.py），Proposal 文件名必须遵循pNNNNN-标题.md的命名约定，这也解释了为何设计文档中的链接文本普遍使用#nnnn编号与pNNNNN文件名。

实战要点小结

撰写或评审 Carbon 语言设计文档时，建议按以下清单自查：

结构：是否包含自动生成的目录、Overview、至少一个详细设计章节、Alternatives considered、References？
Overview 是否 BLUF：读者能否在前几行就明白本设计领域的高层结论？
备选方案是否可追溯：Alternatives considered 是否都链接到了对应的 Proposal 文件章节？
链接文本：Issue/PR 用#nnnn，Proposal 章节用仓库内文件路径 +#章节名；相关设计链接内联，外部资料放 References。
风格一致性：是否遵循 Google 开发者文档风格、使用text -- text双连字符、统一用 "developers" 指代用户、文件头部带许可证注释？
格式化：提交前用prek运行rumdl对 Markdown 进行格式化校验。

遵循这套规范，既能保证 Carbon 设计文档在 docs/design 目录下的统一气质，也能让每一处设计决策都有明确的 Proposal 出处，方便后续语言演进（如 docs/project/evolution.md 所描述的治理流程）中追溯与复查。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析