帮助:格式手册

此页面包含设计指南，旨在帮助在本维基中遵循一致的样式和格式。请注意，该指南列表既不是最终的，也不是完整的，也就是说，如果这样做有好处，可以添加新指南并更改当前指南。

[编辑] 页面结构

本维基中的大多数页面都具有以下模式

[编辑] 标题覆盖

标题覆盖几乎是强制性的，否则 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

命名空间

变体

视图

操作