Delen via

Richtlijnen voor codering

CNTK coderingsstijl

Deze pagina documenteert de conventies die worden gebruikt in de broncode van CNTK. Volg deze conventies bij het schrijven van nieuwe code. Volg gezond verstand en breek functies die een redelijke limiet overschrijden (een aantal schermpagina's), gebruik zinvolle namen, opmerkingen goed en houd opmerkingen en code gesynchroniseerd, enzovoort.

Basisbeginselen: inspringing, afstand en accolades

Code wordt consistent ingesprongen met vier spaties. Tabtekens zijn nergens in de code toegestaan. De enige uitzonderingen zijn Makefiles, ander buildsysteem of gegevensbestanden waarbij tabtekens syntactisch vereist zijn.

De volgende codeblokken worden ingesprongen:

  • Organen van controle-instructies: voor, indien, terwijl, schakelen, enz.
  • Vrije instructieblokken, zoals het openen en sluiten van accolades die geen controle-instructie volgen. Deze worden soms gebruikt om de levensduur van objecten te beperken.
  • Lichamen van klassen en functies.
  • Instructies zijn voortgezet vanaf de vorige regel.
  • Code in case-instructies begint op de regel na de case-instructie en wordt ingesprongen.

De volgende zaken worden niet ingesprongen:

  • Inhoud van naamruimten.
  • Hoofdletterlabels
  • Opgegeven toegangsbeheer.

Functiedeclaraties met lange parameterlijsten kunnen worden gesplitst via meerdere regels. De parameterdeclaratie op de splitslijnen moet worden ingesprongen tot het haakje openen van de functiedeclaratie. Aanroepen naar functies met lange parameterlijsten kunnen worden gesplitst over meerdere regels, de splitslijnen moeten worden ingesprongen op het haakje openen van de bijbehorende functie-instructie.

Code wordt geschreven met behulp van Allman- of BSD Unix-stijl accolades. Met deze stijl wordt de accolade gekoppeld aan een besturingsinstructie op de volgende regel, ingesprongen op hetzelfde niveau als de besturingsinstructie. Instructies binnen de accolades worden ingesprongen naar het volgende niveau. Het wordt aanbevolen om nooit accolades weg te laten, zelfs voor kleine blokken.

Spaties zijn aanwezig op de volgende plaatsen:

  • Rondom alle binaire operatoren, inclusief toewijzingen
  • Tussen een trefwoord en haakjes
  • Tussen een id of trefwoord en een accolade
  • Na komma's en puntkomma's die geen lijn beëindigen

Spaties zijn afwezig op de volgende plaatsen:

  • Vóór puntkomma's en komma's
  • Aan de binnenkant van haakjes
  • Tussen de naam van een functie en de argumentenlijst
  • Tussen unaire operatoren en hun operanden
  • Binnen een lege lijst met argumenten
  • Tussen een label en een dubbele punt
  • Rond de bereikoperator ::

Lijsten met ledeninitiatoren en basisklasselijsten die meer dan één klasse bevatten, moeten op een afzonderlijke regel worden geschreven. Dit maakt het heel eenvoudig om fouten te herkennen.

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

} } }

Naamconventies

  • Namen van klassen en naamruimten maken gebruik van UpperCamelCase, ook wel PascalCase genoemd.
  • Namen die vaak worden gespeld in hoofdletters (SQL, CNTK, ...) kunnen in alle hoofdletters blijven.
  • Globale en openbare statische functies, stackvariabelen en klasseleden (klassevariabelen) maken gebruik van lowerCamelCase.
  • Klasselidfuncties (methoden) gebruiken UpperCamelCase.
  • Macro's en constanten gebruiken UPPER_SNAKE_CASE.
  • Sjabloonparameters die typen zijn, maken gebruik van UpperCamelCase.
  • Typevoorvoegsels, Hongaarse notatie, enzovoort zijn niet toegestaan. Gebruik zinvolle achtervoegsels als u ondubbelzinnig wilt zijn, bijvoorbeeld floatMatrix en normalizedDoubleMatrix.

Naamvoorvoegsels

  • m_ voor lidvariabelen
  • s_ voor statische variabelen in elke context
  • g_ voor globale variabelen, die in de eerste plaats moeten worden vermeden (zoveel mogelijk)

Namen van variabelen moeten zelfstandige naamwoorden zijn. Functienamen moeten werkwoorden zijn, met uitzondering van getters, die zelfstandige naamwoorden kunnen zijn. Een klasseeigenschap met de naam positie heeft bijvoorbeeld de setter SetPosition() en de getter Position().

Bestandsnaamconventies

C++-bestanden moeten de extensie .cpp hebben, terwijl headerbestanden de extensie .h moeten hebben. Spaties en onderstrepingstekens zijn niet toegestaan. Het gebruik van getallen in bestandsnamen wordt afgeraden.

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

Preprocessor

Voorwaardelijke compilatie met de preprocessor wordt sterk afgeraden, omdat dit leidt tot coderot. Gebruik deze alleen als het onvermijdelijk is, bijvoorbeeld wanneer een optionele afhankelijkheid wordt gebruikt. Een speciaal geval maakt gebruik van voorwaardelijke compilatie om een volledig bestand uit te sluiten op basis van het platform, dat is toegestaan.

In de voorkeur voor voorwaardelijk gecompileerde, platformspecifieke code, moet u streven naar het schrijven van draagbare code die hetzelfde werkt, ongeacht het platform. Het gebruik van de Boost-bibliotheken kan op dit gebied veel helpen. Als u verschillende code moet gebruiken, afhankelijk van het platform, probeert u deze in te kapselen in helperfuncties, zodat de hoeveelheid code die verschilt tussen platforms tot een minimum wordt bewaard.

  • Last updated on