ヘルプ:スタイルマニュアル

このページには、このウィキで一貫したスタイルとフォーマットを維持するための設計ガイドラインが含まれています。このガイドラインリストは最終版ではなく、網羅的でもないことに注意してください。つまり、メリットがあれば新しいガイドラインを追加したり、既存のものを変更したりすることができます。

[編集] ページ構造

このウィキのほとんどのページは次のパターンに従っています。

[編集] タイトルオーバーライド

タイトルオーバーライドはほぼ必須です。そうしないと、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 since c++11}} の代わりに {{mark c++11}} をナビゲーションバーで使用する必要があります。

[編集] クラスまたは関数の宣言

宣言はヘッダーに定義されているとおりに配置されます。テンプレート名とパラメータ名は、可能であればこのウィキの一般的な名前に従って変更されます。フォーマットの処理には dcl ファミリのテンプレートが使用されます。

[編集] 説明

説明には通常、クラス/関数/オブジェクトなどの動作を説明する短いテキストと、別のセクションに分類された追加情報 (以下を参照) が含まれます。

説明テキストの最初の文は、その機能の動作を**要約しなければなりません**。その長さは 200 文字 (約 2 行) を超えてはなりません。

[編集] クラス

クラスの説明は、一般的に次のパターン (セクションの順序) に従います。

概要
説明テキスト
クラス不変条件
テンプレートパラメータ (クラスがテンプレートの場合)
メンバー型 (公開/非公開/保護/非公開)
メンバ関数 (公開/非公開/保護/非公開)
メンバーオブジェクト (公開/非公開/保護/非公開)
非メンバ関数
ヘルパー型
ヘルパークラス
注意 (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}}

例えば、コンテナライブラリのように、同じ説明ビットが複数のクラスにわたって使用される場合、1つのテンプレートで最大 20 箇所の重複を排除できます。

[編集] 関数

関数の説明は、一般的に次のパターン (セクションの順序) に従います。

概要
説明テキスト
テンプレートパラメータ (関数がテンプレートの場合)
パラメータ
戻り値
前提条件
事後条件
例外
計算量
注意 (FTM テーブルを含む場合があります)
可能な実装
例
欠陥レポート (もしあれば)
参考文献 (規範的なドキュメントへのリンク)
関連項目
外部リンク (もしあれば)

すべての関数パラメータ名は等幅フォントで記述されます。

par ファミリのテンプレートは、パラメータ説明のフォーマットを処理するために使用されます。

**パラメータ**、**戻り値**、または**例外**などの仕様が空のセクションは省略してください。まだ広く使用されている非推奨のアプローチは、空のセクションを「(none)」タグでマークすることです。

{{eq fun}} または {{eq impl}} を使用して、同等のコード (可能な実装) を提示できます。

{{example}} を使用して例を提示できます。

[編集] オブジェクト、定数、型

オブジェクト、定数、または型の説明には、通常、説明のみが含まれます。

[編集] アルゴリズム関数オブジェクト (ニーブロイド)

アルゴリズム関数オブジェクト (別名ニーブロイド) の説明は、関数と同じパターンに従いますが、導入部には {{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.com

名前空間

変種

表示

操作