Sdílet prostřednictvím

Pokyny pro kódování

styl kódování CNTK

Tato stránka dokumentuje konvence používané ve zdrojovém kódu CNTK. Při psaní nového kódu prosím dodržujte tyto konvence. Sledujte běžné smysly a rozdělte funkce překračující rozumný limit (několik stránek obrazovky), používejte smysluplné názvy, komentujte dobře a udržujte komentáře a kód synchronizované atd.

Základy: odsazení, mezery a závorky

Kód je konzistentně odsazený pomocí čtyř mezer. Znaky tabulátoru nejsou v kódu povoleny. Jedinými výjimkami jsou makefile, jiný systém sestavení nebo datové soubory, kde jsou syntakticky vyžadovány znaky tabulátoru.

Odsazení následujících bloků kódu:

  • Kontrolní příkazy: pro, if, while, switch atd.
  • Bloky volných příkazů, tj. otevírání a zavírání složených závorek, které nesledují žádný řídicí příkaz. Někdy se používají k omezení životnosti objektů.
  • Předměty a funkce.
  • Příkazy pokračovaly z předchozího řádku.
  • Kód v příkazech case začíná na řádku za příkazem case a je odsazený.

Následující položky nejsou odsazené:

  • Obsah oborů názvů
  • Popisky velkých a velkých písmen
  • Specifikátory řízení přístupu

Deklarace funkcí s dlouhými seznamy parametrů mohou být rozděleny na více řádků. Deklarace parametru na rozdělených řádcích by měla být odsazená na levou závorku deklarace funkce. Volání funkcí s dlouhými seznamy parametrů mohou být rozdělena na více řádků, rozdělené řádky by měly být odsazené na levou závorku přidruženého příkazu funkce.

Kód je napsaný pomocí závorek ve stylu Allman nebo BSD Unix. Tento styl umístí závorku přidruženou k ovládacímu příkazu na další řádek odsazený na stejnou úroveň jako příkaz ovládacího prvku. Příkazy v závorkách jsou odsazené na další úroveň, doporučuje se nikdy vynechat složené závorky, dokonce i pro malé bloky.

Mezery jsou přítomné na následujících místech:

  • Kolem všech binárních operátorů, včetně přiřazení
  • Mezi klíčovým slovem a závorky
  • Mezi identifikátorem nebo klíčovým slovem a složenou závorkou
  • Za čárkou a středníky, které nekončí čáru

Mezery chybí na následujících místech:

  • Před středníky a čárky
  • Na vnitřní straně závorek
  • Mezi názvem funkce a seznamem argumentů
  • Mezi unárními operátory a jejich operandy
  • Uvnitř prázdného seznamu argumentů
  • Mezi popiskem a dvojtečku
  • Kolem operátoru oboru::

Seznamy inicializátoru členů a seznamy základních tříd, které obsahují více než jednu třídu, by měly být zapsány na samostatný řádek. Díky tomu je velmi snadné odhalit chyby.

namespace Microsoft { namespace MSR { namespace CNTK {

Matrix ImplodeSelf(int x);
int ConfuseUs(float y);

class MainPart:
    public Head,
    protected Heart
{
public:
    MainPart():
        m_weight(99),
        m_height(180)
    {}
private:
    void EatMore();
    int m_consume, m_repeater;
};

template <typename Box>
void Inspect(Box & container)
{
    switch (container)
    {
    case 1:
        PrepareIt();
        break;

    case 2:
        Finish();
        break;

    default:
        break;
    }

    for (int i = 0; i < 30; ++i)
    {
        container << EatMore();
    }
    return container;
}

} } }

Zásady vytváření názvů

  • Názvy tříd a oborů názvů používají UpperCamelCase aka PascalCase.
  • Názvy běžně napsané v all-caps (SQL, CNTK, ...) můžou zůstat ve všech horních případech.
  • Globální a veřejné statické funkce, proměnné zásobníku a členy třídy (proměnné tříd) používají lowerCamelCase.
  • Členské funkce třídy (metody) používají UpperCamelCase.
  • Makra a konstanty používají UPPER_SNAKE_CASE.
  • Parametry šablony, které jsou typy, používají UpperCamelCase.
  • Předpony typů, maďarská notace atd. jsou zakázány. Použijte smysluplné přípony, pokud potřebujete zrušit nejednoznačnost, například floatMatrix a normalizovanéDoubleMatrix.

Předpony názvů

  • m_ pro členské proměnné
  • s_ pro statické proměnné v libovolném kontextu
  • g_ pro globální proměnné, kterým byste se měli vyhnout na prvním místě (co nejvíce)

Názvy proměnných by měly být podstatná jména. Názvy funkcí by měly být slovesa, s výjimkou getterů, což může být podstatná jména. Například vlastnost třídy s názvem position by měla setter SetPosition() a getter Position().

Konvence názvů souborů

Soubory C++ by měly mít příponu .cpp, zatímco hlavičkové soubory by měly mít příponu .h. Mezery a podtržítka nejsou povoleny. Použití čísel v souborech se nedoporučuje.

#define GOOD_MACRO(x) x
void CallOut();
unsigned const g_theAnswer = 42;

class SolveAllProblems 
{
public:
    void DoWhatWeNeed();
    static void SetBugsOff();
    int m_countReasons;
protected:
    void NeverWorking();
    static void GetReason();
    int internalCounter;
private:
    void InternalNeeds();
    static void ShowReason();
    int m_countShows;
};

template <typename TypeParam, int numberOfReasons>
void CallGlobal(boost::array<TypeParam, numberOfReasons> const &array);

Preprocesor

Podmíněné kompilace pomocí preprocesoru se důrazně nedoporučuje, protože vede k rotci kódu. Používejte ho jenom v případě, že je nepoužitelný, například pokud se použije volitelná závislost. Speciální případ používá podmíněnou kompilaci k vyloučení celého souboru na základě platformy, která je povolená.

V předvolbách podmíněné kompilace kódu specifického pro platformu byste měli za cíl napsat přenosný kód, který funguje stejně bez ohledu na platformu. Používání knihoven Boost může v tomto ohledu hodně pomoct. Pokud musíte použít jiný kód v závislosti na platformě, zkuste ho zapouzdřet v pomocných funkcích, aby se množství kódu, které se liší mezi platformami, bylo zachováno na minimum.

  • Last updated on