Linee guida per la codifica

Articolo
11/14/2016

stile di codifica CNTK

Questa pagina documenta le convenzioni usate nel codice sorgente di CNTK. Rispettare queste convenzioni durante la scrittura di nuovo codice. Seguire il buon senso e suddividere le funzioni che superano un limite ragionevole (un paio di pagine dello schermo), usare nomi significativi, commenti e commenti e codice sincronizzati e così via.

Nozioni di base: rientro, spaziatura e parentesi graffe

Il rientro del codice viene applicato in modo coerente usando quattro spazi. I caratteri di tabulazioni non sono consentiti in nessun punto del codice. Le uniche eccezioni sono Makefile, altri file di compilazione o file di dati in cui i caratteri di tabulazioni sono sintatticamente necessari.

I blocchi di codice seguenti sono rientrati:

Corpi di istruzioni di controllo: per, se, while, switch e così via.
Blocchi di istruzioni free, ad esempio le parentesi graffe di apertura e chiusura che non seguono alcuna istruzione di controllo. Questi oggetti vengono talvolta usati per limitare la durata degli oggetti.
Corpi di classi e funzioni.
Le istruzioni sono continuate dalla riga precedente.
Il codice nelle istruzioni case inizia nella riga che segue l'istruzione case e viene rientrato.

I seguenti elementi non sono rientrati:

Contenuto degli spazi dei nomi.
Etichette case
Identificatori di controllo di accesso.

Le dichiarazioni di funzione con elenchi di parametri lunghi possono essere suddivise su più righe. La dichiarazione di parametro nelle righe di divisione deve essere rientrata nella parentesi di apertura della dichiarazione di funzione. Le chiamate alle funzioni con elenchi di parametri lunghi possono essere suddivise su più righe, le righe suddivise devono essere rientrate nella parentesi di apertura dell'istruzione di funzione associata.

Il codice viene scritto usando parentesi graffe di stile Allman o BSD Unix. Questo stile inserisce la parentesi graffa associata a un'istruzione del controllo nella riga successiva, rientrata allo stesso livello dell'istruzione del controllo. Le istruzioni all'interno delle parentesi graffe vengono rientrate al livello successivo, è consigliabile non omettere mai parentesi graffe, anche per blocchi di piccole dimensioni.

Gli spazi sono presenti nelle posizioni seguenti:

Intorno a tutti gli operatori binari, incluse le assegnazioni
Tra parole chiave e parentesi
Tra un identificatore o una parola chiave e una parentesi graffa
Dopo virgole e punti e virgola che non terminano una riga

Gli spazi sono assenti nelle posizioni seguenti:

Prima dei punti e virgola e delle virgole
Sul lato interno delle parentesi
Tra un nome di funzione e il relativo elenco di argomenti
Tra operatori unari e i relativi operandi
All'interno di un elenco di argomenti vuoto
Tra un'etichetta e due punti
Intorno all'operatore di ambito ::

Gli elenchi di inizializzatori membri e gli elenchi di classi base che contengono più di una classe devono essere scritti in una riga separata. In questo modo è molto facile individuare gli errori.

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

} } }

Convenzioni di denominazione

I nomi di classe e spazio dei nomi usano UpperCamelCaseka PascalCase.
I nomi comunemente digitati in maiuscolo (SQL, CNTK, ...) possono rimanere in tutti i maiuscole.
Le funzioni statiche globali e pubbliche, le variabili dello stack e i membri della classe (variabili di classe) usano lowerCamelCase.
Le funzioni membro di classe (metodi) usano UpperCamelCase.
Le macro e le costanti usano UPPER_SNAKE_CASE.
I parametri del modello che sono tipi usano UpperCamelCase.
I prefissi di tipo, la notazione ungherese e così via non sono consentiti. Usare suffissi significativi se è necessario disambiguare, ad esempio floatMatrix e normalizedDoubleMatrix.

Prefissi dei nomi

m_ per le variabili membro
s_ per le variabili statiche in qualsiasi contesto
g_ per le variabili globali, che devono essere evitate al primo posto (il più possibile)

I nomi delle variabili devono essere sostantivi. I nomi delle funzioni devono essere verbi, ad eccezione dei getter, che possono essere sostantivi. Ad esempio, una proprietà di classe denominata position avrà il setter SetPosition() e il getter Position().

Convenzioni del nome file

I file C++ devono avere l'estensione cpp, mentre i file di intestazione devono avere l'estensione h. Gli spazi e i caratteri di sottolineatura non sono supportati. L'uso di numeri nei nomi di file è sconsigliato.

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

Preprocessore

La compilazione condizionale che usa il preprocessore è fortemente sconsigliata, poiché comporta un errore di codice. Usarlo solo quando è inevitabile, ad esempio quando viene usata una dipendenza facoltativa. Un caso speciale consiste nell'usare la compilazione condizionale per escludere un intero file in base alla piattaforma, consentita.

In preferenza per compilare in modo condizionale codice specifico della piattaforma, è consigliabile scrivere codice portabile che funziona allo stesso modo indipendentemente dalla piattaforma. L'uso delle librerie Boost può aiutare molto in questo senso. Se è necessario usare codice diverso a seconda della piattaforma, provare a incapsularlo nelle funzioni helper, in modo che la quantità di codice diversa tra le piattaforme venga mantenuta al minimo.

Condividi tramite