帮助：样式手册

此页面包含设计指南，有助于遵循此 wiki 中的一致样式和格式。请注意，指南列表既不是最终的也不是完整的，即，如果这样做有益，可以添加新的指南并更改当前指南。

页面结构

此 wiki 中的大多数页面都遵循以下模式

标题覆盖

标题覆盖几乎是强制性的，否则 MediaWiki 会显示页面的路径。

如果该功能不属于任何类，则使用 {{ctitle}} 或 {{cpp/title}} 直接覆盖标题。否则，将创建一个抽象容器类名的辅助模板。例如，考虑 std::class::func()

cpp/blah/class/func 包含 {{cpp/blah/class/title|func}}

而 Template:cpp/blah/class/title 包含 {{cpp/title|n=class|{{{1}}}}}。此辅助模板用于该类的所有成员。

导航栏

导航栏用于通过提供指向相关页面的链接来改善导航。导航栏通常使用 {{navbar}} 模板实现。生成的定义通常放在 Template:path/to/page/navbar 中。

{{navbar}} 模板定义了一个始终可见的标题和悬停时显示的内容。这两个定义通常分别放在 Template:path/to/page/navbar heading 和 Template:path/to/page/navbar content 中的单独模板中。

内容通常是相关函数和类的列表。列表通常使用 nv 模板系列实现。

导航栏的定义包括其每个父页面的标题和内容模板。

{{mark c++11}} 应在导航栏中使用，而不是 {{mark since c++11}}，以节省空间。

类或函数的声明

声明按在头文件中定义的方式放置。模板和参数名称如果可能，将根据此 wiki 中的通用名称重命名。 dcl 模板系列用于处理格式化。

描述

描述通常包含一些解释类/函数/对象/等的行为的文本，以及分类到单独部分的附加信息（见下文）。

描述文本的第一句话必须概括该功能的行为。它的长度不应超过约 200 个字符（大约两行文本）。

类

类的描述通常遵循以下模式（按顺序列出部分）

• 概要
• 描述文本
• 模板参数（如果类是模板）
• 成员类型（公共/私有/保护/仅供说明）
• 成员函数（公共/私有/保护/仅供说明）
• 成员对象（公共/私有/保护/仅供说明）
• 非成员函数
• 辅助类型
• 辅助类
• 说明（可能包括 FTM 表格）
• 示例
• 缺陷报告（如果有）
• 参考（指向规范文档的链接）
• 另请参见
• 外部链接（如果有）

dsc 模板系列用于处理成员类型、函数或对象的列表的格式，以及相关非成员函数或类的列表的格式。

通常，相同的成员描述位（例如 {{dsc mem fun| cpp/component/class/fun_function| 函数的描述}}) 将被包含到其他页面的另请参见部分中。为了减少重复，值得将这些位放到单独的模板中，然后使用 {{dsc inc}} 来包含它们。

例如

在 cpp/component/class 中

 
  {{dsc begin}}
  {{dsc h1 | Member functions}}
  {{dsc inc | cpp/component/class/dsc fun_function}}
  {{dsc end}}
  

在 cpp/component/class/another_function 中

 
  ...
  ...
  ===See also===
  {{dsc begin}}
  {{dsc inc | cpp/component/class/dsc fun_function}}
  {{dsc end}}
  

在 Template:cpp/component/class/dsc fun_function 中

 
  {{dsc mem fun | cpp/component/class/fun_function | description of the function}}
  

如果相同的描述位在多个类中使用，例如在容器库中，一个模板可以消除多达 20 个地方的重复。

函数

函数的描述通常遵循以下模式（按顺序列出部分）

• 概要
• 描述文本
• 模板参数（如果函数是模板）
• 参数
• 返回值
• 异常
• 复杂度
• 说明（可能包括 FTM 表格）
• 可能的实现
• 示例
• 缺陷报告（如果有）
• 参考（指向规范文档的链接）
• 另请参见
• 外部链接（如果有）

所有函数参数名称都以 等宽字体 编写。

par 模板系列用于处理参数描述的格式。

（无）用于表示缺少参数、返回值或抛出的异常。

{{eq fun}} 可用于格式化等效代码

{{example}} 可用于格式化示例

对象、常量、类型

对象、常量或类型的描述通常只包含描述。

Niebloids

Niebloid 的描述通常遵循与函数相同的模式，除了引言应包含 {{cpp/ranges/niebloid}} (?)

概念

概念的描述通常只包含描述。

另请参见列表

列出相关函数、类等。{{dsc ...}} 模板系列用于处理格式。

代码格式

大写

名称按与大多数 C++ 标准相同的方式大写。标准组件的文档应遵循以下样式

• 函数参数使用 小写 样式
• 模板参数使用 驼峰式 样式

在示例和其他文档中，以下附加指南适用

• 自定义类名使用 驼峰式 样式
• 变量名使用 小写 样式
• 宏和常量名使用 全部大写 样式

间距和缩进

• 使用 K&R 缩进样式（见 K&R TBS）。
• 标准结构，即 for、while、if 等在标识符和左括号之间有一个空格，例如
  for (...).
• 函数名和括号之间没有空格，括号和它们之间内容之间也没有空格，例如 fun(...)。
• 模板名和 < 符号之间没有空格，< 和 > 符号和模板参数之间也没有空格，例如 tmp<...>。
• 多个函数或模板参数用逗号后面的空格隔开。
• 引用和指针（& 和 *）修饰符和类型名称之间没有空格（例如 int& b）。
• 如果函数的参数跨越多行，则所有参数的缩进与左括号匹配。模板参数也是如此。

例如

#include <vector>
 
std::vector<int, MyAllocator> v;
 
int complex_function(int long_param_name,
                     int& another_param_name);
 
int main(int argc, char* argv[])
{
    if (argc == 2)
    {
        std::cout << argv[0] << '\n';
        std::cout << argv[1] << '\n';
    }
    else
        std::cout << argv[0] << '\n';
}

并非所有这些规则都适用于详细的功能声明（那些进入 {{dcl ***}} 模板的），因为需要额外的可读性。例外包括

• 在 < 和 > 符号和函数模板的模板参数之间有空格。
• 类模板的参数通过多行排列。
• 对于作为模板的函数参数，< 和 > 符号和模板参数之间没有空格。此外，在分隔模板参数的逗号之后没有空格。

例如

template <     class TemplateParam,     class TemplateParam2 > class TemplateClass;
template< class TemplateParam, class TemplateParam2 > int function_template( MyTemplate<T,Param> my_template_param,                        int* other_param );