帮助：风格手册

此页面包含一个设计指南，旨在帮助在本维基中保持一致的风格和格式。请注意，此指南列表既非最终也非完整，即可以添加新的指南，并且如果有利，可以更改当前的指南。

[编辑] 页面结构

本维基的大多数页面遵循以下模式

[编辑] 标题覆盖

标题覆盖几乎是强制性的，否则 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}}，以节省空间。

[编辑] 类或函数的声明

声明按照头文件中定义的方式放置。模板和参数名称尽可能根据本维基中的常用名称进行重命名。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 模板族用于处理参数描述的格式。

应省略参数、返回值或异常等规范的空章节。一种已弃用但仍广泛使用的方法是用“(none)”标签标记空章节。

{{eq fun}} 或 {{eq impl}} 可用于呈现等效代码（可能的实现）。

{{example}} 可用于呈现示例。

[编辑] 对象、常量、类型

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

[编辑] 算法函数对象（niebloids）

算法函数对象（又称 niebloid）的描述通常遵循与函数相同的模式，但引言中应包含 {{cpp/ranges/niebloid}}。

[编辑] 概念

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

[编辑] 另请参见列表

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

[编辑] 代码格式

[编辑] 大小写

名称的大小写方式与大多数 C++ 标准中的方式相同。标准组件的文档应遵循以下风格：

函数参数使用 small_caps 风格
模板参数使用 CamelCase 风格

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

自定义类名使用 CamelCase 风格
变量名使用 small_caps 风格
宏和常量名使用 ALL_CAPS 风格

[编辑] 间距和缩进

使用 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 = nullptr );

[编辑] 另请参见

帮助：模板

cppreference.cn

命名空间

变体

视图

操作