Kodlama Yönergeleri

Makale
11/14/2016

CNTK Kodlama Stili

Bu sayfa, CNTK kaynak kodunda kullanılan kuralları belgelemektedir. Lütfen yeni kod yazarken bu kurallara uyun. Makul bir sınırı (birkaç ekran sayfası) aşan sağduyu ve ayırma işlevlerini izleyin, anlamlı adlar kullanın, iyi yorum yapın, açıklamaları ve kodları eşitleyin vb.

Temel bilgiler: girinti, aralık ve ayraçlar

Kod, dört boşluk kullanılarak tutarlı bir şekilde girintili hale eklenir. Sekme karakterlerine kodun hiçbir yerinde izin verilmez. Tek özel durumlar, sekme karakterlerinin bozulmadan gerekli olduğu Derleme dosyaları, diğer derleme sistemi veya veri dosyalarıdır.

Aşağıdaki kod bloklarının girintisi oluşturulur:

Denetim deyimlerinin gövdeleri: for, if, while, switch vb.
Serbest deyim blokları, yani herhangi bir denetim deyimini izlemeyen açma ve kapatma ayraçları. Bunlar bazen nesnelerin ömrünü sınırlamak için kullanılır.
Sınıfların ve işlevlerin gövdeleri.
Deyimler önceki satırdan devam etti.
Servis talebi deyimlerindeki kod, servis talebi deyiminden sonra satırda başlar ve girintili olur.

Aşağıdaki öğeler girintili değildir:

Ad alanlarının içeriği.
Büyük/küçük harf etiketleri
Erişim denetimi tanımlayıcıları.

Uzun parametre listelerine sahip işlev bildirimleri birden çok satıra bölünebilir. Bölünmüş satırlardaki parametre bildirimi, işlev bildiriminin açılış parantezine girintili olmalıdır. Uzun parametre listelerine sahip işlevlere yapılan çağrılar birden çok satıra bölünebilir, bölünmüş satırlar ilişkili işlev deyiminin açılış parantezine girintili olmalıdır.

Kod, Allman veya BSD Unix stil ayraçları kullanılarak yazılır. Bu stil, bir denetim deyimiyle ilişkilendirilmiş ayraçları bir sonraki satıra yerleştirir ve girintili olarak denetim deyimiyle aynı düzeye gelir. Küme ayraçları içindeki deyimler bir sonraki düzeye girintilenir, küçük bloklar için bile küme ayraçlarını atlamayın.

Boşluklar aşağıdaki yerlerde bulunur:

Atamalar dahil olmak üzere tüm ikili işleçler çevresinde
Anahtar sözcük ve parantezler arasında
Tanımlayıcı veya anahtar sözcük ile ayraç arasında
Bir çizgiyi sonlandırmayan virgül ve noktalı virgülden sonra

Aşağıdaki yerlerde boşluklar yoktur:

Noktalı virgül ve virgülden önce
Parantezlerin iç tarafında
İşlev adı ile bağımsız değişken listesi arasında
Birli işleçler ve işlenenleri arasında
Boş bir bağımsız değişken listesinin içinde
Bir etiket ile iki nokta üst üste arasında
Kapsam işlecinin çevresinde ::

Birden fazla sınıf içeren üye başlatıcı listeleri ve temel sınıf listeleri ayrı bir satıra yazılmalıdır. Bu, hataları saptamayı çok kolaylaştırır.

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

} } }

Adlandırma kuralları

Sınıf ve ad alanı adları UpperCamelCase veya PascalCase kullanır.
Tümü büyük harfle yazılmış adlar (SQL, CNTK, ...) tüm büyük harflerde kalabilir.
Genel ve genel statik işlevler, yığın değişkenleri ve sınıf üyeleri (sınıf değişkenleri) lowerCamelCase kullanır.
Sınıf üyesi işlevleri (yöntemler) UpperCamelCase kullanır.
Makrolar ve sabitler UPPER_SNAKE_CASE kullanır.
Tür olan şablon parametreleri UpperCamelCase kullanır.
Tür ön eklerine, Macarca gösterimine vb. izin verilmiyor. Örneğin floatMatrix ve normalizedDoubleMatrix gibi belirsizliği gidermeniz gerekiyorsa anlamlı sonekler kullanın.

Ad ön ekleri

m_ üye değişkenleri için
s_ herhangi bir bağlamdaki statik değişkenler için
g_ en başta kaçınılması gereken genel değişkenler için (mümkün olduğunca)

Değişken adları ad olmalıdır. İşlev adları, adlar olabilecek getter'lar dışında fiiller olmalıdır. Örneğin, position adlı bir sınıf özelliği setter SetPosition() ve getter Position() değerine sahip olabilir.

Dosya adı kuralları

C++ dosyaları .cpp uzantısına, üst bilgi dosyaları ise .h uzantısına sahip olmalıdır. Boşluklara ve alt çizgilere izin verilmez. Dosya adlarında sayıların kullanılması önerilmez.

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

Ön işlemci

Önişlemciyi kullanan koşullu derleme kesinlikle önerilmez çünkü kod çürümesine yol açar. Bunu yalnızca kaçınılmaz olduğunda, örneğin isteğe bağlı bir bağımlılık kullanıldığında kullanın. Özel bir durum, izin verilen platformu temel alan bir dosyanın tamamını dışlamak için koşullu derleme kullanmaktır.

Koşullu olarak derlenmiş, platforma özgü kod tercihi olarak, platformdan bağımsız olarak aynı şekilde çalışan taşınabilir kod yazmayı hedeflemeniz gerekir. Boost kitaplıklarını kullanmak bu konuda çok yardımcı olabilir. Platforma bağlı olarak farklı kod kullanmanız gerekiyorsa, platformlar arasında farklılık gösteren kod miktarının en düşük düzeyde tutulması için bunu yardımcı işlevlerde kapsüllemeye çalışın.

Aracılığıyla paylaş