Hilfe:Gestaltungsrichtlinien

Diese Seite enthält eine Designrichtlinie, die hilft, einen konsistenten Stil und eine einheitliche Formatierung in diesem Wiki zu befolgen. Beachten Sie, dass die Liste der Richtlinien weder endgültig noch vollständig ist, d.h. neue Richtlinien können hinzugefügt und bestehende geändert werden, wenn dies vorteilhaft ist.

Seitenstruktur

Die meisten Seiten in diesem Wiki haben folgendes Muster

Titelüberschreibung

Die Titelüberschreibung ist fast zwingend erforderlich, da MediaWiki sonst den Pfad der Seite anzeigt.

Wenn das Feature kein Mitglied einer Klasse ist, wird der Titel direkt mit {{ctitle}} oder {{cpp/title}} überschrieben. Andernfalls wird eine Hilfsvorlage erstellt, die den Namen der Containerklasse abstrahiert. Betrachten Sie zum Beispiel std::class::func()

cpp/blah/class/func enthält {{cpp/blah/class/title|func}}

während Template:cpp/blah/class/title {{cpp/title|n=class|{{{1}}}}} enthält. Diese Hilfsvorlage wird für alle Mitglieder dieser Klasse verwendet.

Navigationsleiste

Navigationsleisten werden verwendet, um die Navigation durch Links zu relevanten Seiten zu verbessern. Eine Navigationsleiste wird normalerweise mit der Vorlage {{navbar}} implementiert. Die resultierende Definition wird normalerweise unter Template:path/to/page/navbar abgelegt.

Die Vorlage {{navbar}} definiert eine Überschrift, die immer sichtbar ist, und Inhalte, die beim Überfahren mit der Maus angezeigt werden. Die Definitionen beider werden normalerweise in separaten Vorlagen unter Template:path/to/page/navbar heading und Template:path/to/page/navbar content abgelegt.

Der Inhalt ist normalerweise eine Liste verwandter Funktionen und Klassen. Die Liste wird normalerweise mit der nv-Familie von Vorlagen implementiert.

Die Definition der Navigationsleiste umfasst die Überschriften- und Inhaltsvorlagen jeder ihrer übergeordneten Seiten.

{{mark c++11}} sollte in Navigationsleisten anstelle von {{mark since c++11}} verwendet werden, um Platz zu sparen.

Deklaration der Klasse oder Funktion

Die Deklaration wird so übernommen, wie sie in der Headerdatei definiert ist. Vorlagen- und Parameternamen werden, wenn möglich, gemäß den gebräuchlichen Namen in diesem Wiki umbenannt. Die Vorlagen der Familie dcl werden zur Formatierung verwendet.

Beschreibung

Die Beschreibung enthält normalerweise einen kurzen Text, der das Verhalten der Klasse/Funktion/des Objekts/etc. erklärt, sowie zusätzliche Informationen, die in separate Abschnitte unterteilt sind (siehe unten).

Der erste Satz des Beschreibungstexts *muss* das Verhalten des Features zusammenfassen. Seine Länge sollte etwa 200 Zeichen nicht überschreiten (das sind etwa zwei Textzeilen).

Klassen

Die Beschreibung einer Klasse folgt im Allgemeinen dem folgenden Muster (Liste der Abschnitte in Reihenfolge)

• Synopsis
• Beschreibungstext
• Das Klasseninvariant
• Vorlagenparameter (wenn die Klasse eine Vorlage ist)
• Mitgliedstypen (öffentlich/privat/geschützt/nur-zur-Veranschaulichung)
• Mitgliedsfunktionen (öffentlich/privat/geschützt/nur-zur-Veranschaulichung)
• Mitgliedsobjekte (öffentlich/privat/geschützt/nur-zur-Veranschaulichung)
• Nicht-Member-Funktionen
• Hilfstypen
• Hilfsklassen
• Hinweise (kann eine FTM-Tabelle enthalten)
• Beispiel
• Fehlerberichte (falls vorhanden)
• Referenzen (Links zu den normativen Dokumenten)
• Siehe auch
• Externe Links (falls vorhanden)

Die Vorlagenerien ::dsc wird zur Formatierung von Listen von Mitgliedstypen, -funktionen oder -objekten sowie Listen verwandter nicht-member-Funktionen oder -klassen verwendet.

Normalerweise werden dieselben Beschreibungsteile für Mitglieder (z.B. {{dsc mem fun| cpp/komponente/klasse/funktion_funktion| beschreibung der funktion}}) in den Abschnitt Siehe auch anderer Seiten aufgenommen. Um Duplizierungen zu reduzieren, lohnt es sich, diese Teile in separaten Vorlagen abzulegen und dann {{dsc inc}} zu verwenden, um sie einzubinden.

Zum Beispiel

In cpp/komponente/klasse

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

In cpp/komponente/klasse/andere_funktion

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

In Template:cpp/komponente/klasse/dsc_fun_funktion

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

Wenn dieselben Beschreibungsteile über mehrere Klassen hinweg verwendet werden, wie z.B. in der Containerbibliothek, kann eine Vorlage Duplikate an bis zu 20 Stellen beseitigen.

Funktionen

Die Beschreibung einer Funktion folgt im Allgemeinen dem folgenden Muster (Liste der Abschnitte in Reihenfolge)

• Synopsis
• Beschreibungstext
• Vorlagenparameter (wenn die Funktion eine Vorlage ist)
• Parameter
• Rückgabewert
• Vorbedingungen
• Nachbedingungen
• Ausnahmen
• Komplexität
• Hinweise (kann eine FTM-Tabelle enthalten)
• Mögliche Implementierung
• Beispiel
• Fehlerberichte (falls vorhanden)
• Referenzen (Links zu den normativen Dokumenten)
• Siehe auch
• Externe Links (falls vorhanden)

Alle Namen von Funktionsparametern werden in Monospace-Schrift geschrieben.

Die Vorlagenerie par wird zur Formatierung von Parameterbeschreibungen verwendet.

Leere Abschnitte für Parameter, Rückgabewert oder Ausnahmen usw. sollten weggelassen werden. Ein veralteter Ansatz, der immer noch weit verbreitet ist, ist die Kennzeichnung leerer Abschnitte mit dem Tag "(none)".

{{eq fun}} oder {{eq impl}} können verwendet werden, um einen äquivalenten Code (mögliche Implementierungen) darzustellen.

{{example}} kann verwendet werden, um Beispiele darzustellen.

Objekt, Konstante, Typen

Die Beschreibung eines Objekts, einer Konstanten oder eines Typs enthält im Allgemeinen nur eine Beschreibung.

Algorithmus-Funktionsobjekte (Niebloids)

Die Beschreibung eines *Algorithmus-Funktionsobjekts* (auch Niebloid genannt) folgt im Allgemeinen demselben Muster wie die einer Funktion, außer dass die Einleitung {{cpp/ranges/niebloid}} enthalten sollte.

Konzepte

Die Beschreibung eines Konzepts enthält im Allgemeinen nur eine Beschreibung.

Siehe auch-Liste

Listet relevante Funktionen, Klassen usw. auf. Die Vorlagenerie {{dsc ...}} wird zur Formatierung verwendet.

Codeformatierung

Groß-/Kleinschreibung

Namen werden so großgeschrieben, wie in den meisten C++-Standards. Die Dokumentation der Standardkomponenten sollte dem folgenden Stil folgen

• Funktionsparameter verwenden den Stil kleinschrift
• Vorlagenparameter verwenden den Stil CamelCase

In Beispielen und anderen Dokumentationen gelten folgende zusätzliche Richtlinien

• Benutzerdefinierte Klassennamen verwenden den Stil CamelCase
• Variablennamen verwenden den Stil kleinschrift
• Makro- und Konstantenamen verwenden den Stil ALLE_GROSSBUCHSTABEN

Abstände und Einrückung

• Der K&R-Einrückungsstil wird verwendet (siehe K&R TBS).
• Standardkonstrukte, d.h. for, while, if, etc. haben ein Leerzeichen zwischen Bezeichner und öffnender Klammer, z.B.
  for (...).
• Es gibt kein Leerzeichen zwischen Funktionsnamen und Klammern sowie zwischen Klammern und dem Inhalt dazwischen, z.B. fun(...).
• Es gibt kein Leerzeichen zwischen dem Vorlagennamen und dem <-Symbol sowie zwischen den <- und >-Symbolen und den Vorlagenparametern, z.B. tmp<...>.
• Mehrere Funktions- oder Vorlagenparameter werden durch ein Leerzeichen *nach* dem Komma getrennt.
• Es gibt kein Leerzeichen zwischen Referenz- und Zeiger-Modifikatoren (& und *) und dem Typnamen (z.B. int& b).
• Wenn sich die Parameter einer Funktion über mehrere Zeilen erstrecken, entspricht die Einrückung aller Parameter der öffnenden Klammer. Dasselbe gilt für Vorlagenparameter.

Zum Beispiel

#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';
}

Nicht alle diese Regeln gelten für die detaillierten Feature-Deklarationen (die in die {{dcl ***}}-Vorlage eingehen), da zusätzliche Lesbarkeit erforderlich ist. Die Ausnahmen sind:

• Es gibt ein Leerzeichen zwischen den <- und >-Symbolen und den Vorlagenparametern für Funktionsvorlagen.
• Klassenvorlagen haben ihre Parameter über mehrere Zeilen verteilt.
• Für Funktionsparameter, die Vorlagen sind, gibt es keine Leerzeichen zwischen den <- und >-Symbolen und den Vorlagenparametern. Außerdem gibt es kein Leerzeichen nach dem Komma, das die Vorlagenparameter trennt.

Zum Beispiel

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 );

Siehe auch

• Hilfe:Vorlagen