it-swarm.asia

Yorum kodunun stili ve önerileri

Kodunuzda yorum yazma konusunda herhangi bir öneri ve deneyim duymak istiyorum. Onları en kolay ve bilgilendirici bir şekilde nasıl yazıyorsunuz? Kodun bölümlerini yorumlarken hangi alışkanlıklarınız var? Belki bazı egzotik öneriler?

Umarım bu soru, herkesin öğrenebileceği faydalı bir şey olan en ilginç önerileri ve önerileri toplar.

Tamam, başlayacağım.

  1. Genellikle /* */ yorum hatta birçok satır yorum yapmak gerektiğinde.

    Avantajlar: Kod, bu sözdizimini tek satırlık yorumlarla karıştırdığınızdan daha iyi görünür. IDE'lerin çoğu seçilen metni yorumlama yeteneğine sahiptir ve genellikle tek satır sözdizimi ile yaparlar.

    Dezavantajları: IDE olmadan bu kodu düzenlemek zor.

  2. Bitmiş herhangi bir yorumun sonuna "nokta" yazın.

    Örneğin:

    //Recognize wallpaper style. Here I wanted to add additional details
    int style = int.Parse(styleValue);
    //Apply style to image.
    Apply(style);
    

    Avantajlar: "Nokta" yı yalnızca bitirdiğiniz yorumlara yerleştirin. Bazen geçici bilgiler yazabilirsiniz, bu nedenle "nokta" eksikliği size geri dönmek ve bu yoruma başka bir metin eklemek istediğinizi söyler.

  3. Numaralandırma, açıklama parametreleri vb. İçindeki metni hizalayın.

    Örneğin:

    public enum WallpaperStyle
    {
        Fill = 100,     //WallpaperStyle = "10"; TileWallpaper = "0".
        SizeToFit = 60, //WallpaperStyle = "6";  TileWallpaper = "0".
        Stretch = 20,   //WallpaperStyle = "2";  TileWallpaper = "0".
        Tile = 1,       //WallpaperStyle = "0";  TileWallpaper = "1".
        Center = 0      //WallpaperStyle = "0";  TileWallpaper = "0".
    };
    

    Avantajları: İhtiyacınız olanı bulmak daha iyi ve görsel olarak daha kolay görünüyor.

    Dezavantajları: Hizalamak için zaman harcamak ve düzenlemek daha zor.

  4. Kodu analiz ederek elde edemeyeceğiniz bir yorum yazın.

    Örneğin, aptalca bir yorum:

    //Apply style.
    Apply(style);
    

    Avantajları: Açıklamalı ve küçük bir koda sahip olacaksınız.

27
Kyrylo M

Aşağıdaki ifadelerden bazıları oldukça gerekçeli olsa da oldukça kişiseldir ve bu şekilde olması amaçlanmıştır.

Yorum Türleri

Kısa sürüm için ... için yorumları kullanıyorum:

  • veri yapılarındaki alanları açıklayan son yorumlar (bunların dışında tek satır yorumları kullanmıyorum)
  • blokların üstünde istisnai veya amaca yönelik çok satırlı yorumlar
  • kaynaktan oluşturulan genel kullanıcı ve/veya geliştirici belgeleri

Ayrıntılar ve (muhtemelen belirsiz) nedenler için aşağıyı okuyun.

Sondaki Yorumlar

Dile bağlı olarak, tek satırlı yorumlar veya çok satırlı yorumlar kullanma. Neden bağlıdır? Bu sadece bir standardizasyon sorunu. C kodu yazdığımda, varsayılan olarak eski moda ANSI C89 kodunu tercih ederim, bu yüzden her zaman /* comments */.

Bu nedenle, çoğu zaman C bu olurdu ve bazen C benzeri bir sözdizimi olan diller için (kod temeli stiline bağlıdır):

typedef struct STRUCT_NAME {
    int fieldA;                /* aligned trailing comment */
    int fieldBWithLongerName;  /* aligned trailing comment */
} TYPE_NAME;

Emacs güzel ve bunu benim için M-;.

Dil tek satırlı yorumları destekliyorsa ve C tabanlı değilse, tek satırlı yorumları kullanmak için daha fazla etkileşimde bulunacağım. Aksi takdirde, korkarım şimdi alışkanlığı aldım. Bu beni çok zorlamayacak kadar kötü değil.

Çok Satırlı Yorumlar

Daha görsel olarak çekici olduğu için tek satırlı yorumları kullanarak önyargınıza katılmıyorum. Bunu kullanıyorum:

/*
 * this is a multi-line comment, which needs to be used
 * for explanations, and preferably be OUTSIDE the a
 * function's or class' and provide information to developers
 * that would not belong to a generated API documentation.
 */

Ya da bu (ama kişisel kod tabanları dışında veya çoğunlukla telif hakkı bildirimleri hariç, daha sık kullanmıyorum - bu benim için tarihi ve eğitim geçmişimden geliyor. Ne yazık ki, çoğu IDE otomatik kullanırken -Format):

/*
** this is another multi-line comment, which needs to be used
** for explanations, and preferably be OUTSIDE the a
** function's or class' and provide information to developers
** that would not belong to a generated API documentation.
*/

Gerçekten olması gerekiyorsa, o zaman sondaki yorumları için daha önce bahsettiğim şeyleri kullanarak satır içi yorum yapardım, eğer onu bir pozisyonda kullanmak mantıklıysa. Çok özel bir iade durumunda, örneğin veya switch 's case ifadelerini (nadiren, anahtarı sık kullanmıyorum) veya bir if ... else kontrol akışı. Bunlardan biri değilse, genellikle fonksiyonun/yöntemin/bloğun adımlarını özetleyen kapsamın dışındaki bir yorum bloğu benim için daha anlamlı olur.

Bunları, dokümantasyon yorumları için destek olmadan bir dilde kodlama dışında çok istisnai olarak kullanıyorum (aşağıya bakın); bu durumda daha yaygın hale gelirler. Ancak genel durumda, gerçekten sadece diğer geliştiriciler için tasarlanmış ve gerçekten öne çıkması gereken iç yorumlar olan şeyleri belgelemek içindir. Örneğin, "zorunlu" catch bloğu gibi zorunlu bir boş bloğu belgelemek için:

try {
    /* you'd have real code here, not this comment */
} catch (AwaitedException e) {
    /*
     * Nothing to do here. We default to a previously set value.
     */
}

Bu benim için zaten çirkin ama bazı durumlarda tahammül ederdim.

Dokümantasyon Yorumları

Javadoc ve ark.

Genellikle bir özellik tanıtan (veya değiştiren) sürümleri belgelemek ve özellikle genel bir API içinse ve bazı örnekler sağlamak için (net giriş ve çıkış durumları ve özel durumlar ile) bunları yöntemlerde ve sınıflarda kullanırdım. Bazı durumlarda bir ünite durumu bunları belgelemek için daha iyi olabilir, ancak ünite testleri mutlaka insan tarafından okunabilir değildir (hangi DSL ürününü kullanırsanız kullanın).

Bunun için sondaki yorumları tercih ettiğim ve tüm dokümantasyon oluşturma çerçevesi sondaki doküman yorumlarını desteklemediğinden, alanları/özellikleri belgelemek için beni rahatsız ediyorlar. Doxygen, örneğin, JavaDoc yapmaz, bu da tüm alanlarınız için en iyi yoruma ihtiyacınız olduğu anlamına gelir. Ancak Java satırları her zaman nispeten uzun olsa da, hayatta kalabilirim, bu nedenle bir yorum, çizgiyi tolerans eşiğimin ötesine uzatarak eşit derecede sürünür. bunu geliştirdiğim halde çok daha mutlu olurdum.

Yorum Yazılan Kod

C-benzeri dillerde sadece tek bir sebeple tek satır kullanıyorum (bunları gerçekten kullanmadığım katı C için derleme dışında): kodlama sırasında bir şeyleri yorumlamak için. Çoğu IDE tek satırlı yorumlar arasında geçiş yapar (girintiye veya 0 sütununa hizalanır) ve bu durum benim için uygun olanıdır. Çok satırlı yorumlar için geçişi kullanmak (veya bazı IDE'ler için satırların ortasından seçim yapmak) yorum/açıklamayı kolayca değiştirmeyi zorlaştıracaktır.

Ama SCM'de yorumlanmış kodlara karşı olduğum için, genellikle çok kısa sürdü çünkü taahhütte bulunmadan önce yorumlanmış parçaları sileceğim. ( cevabım"satır yorumları ve SCM'lerde düzenlenmiş" konusunu okuyun)

Yorum Stilleri

Genellikle yazma eğilimindeyim:

  • daha sonra bir API belgesinde veya hatta oluşturulan kılavuzun bir parçası olarak okunmaları gerektiği için, dokümantasyon yorumları için doğru dilbilgisi (noktalama işaretleri dahil) içeren tam cümleler.
  • çok satırlı yorum blokları için iyi biçimlendirilmiş ancak noktalama işaretlerinde daha fazla gevşeklik
  • noktalama işareti olmayan sondaki bloklar (boşluk nedeniyle ve genellikle yorum kısa olduğu için, daha çok parantez içine alınmış bir ifade gibi okunur)

Literate Programming üzerine bir not

Literate Programming , bu Donald Knuth bölümünde anlatıldığı gibi ilgilenmek isteyebilirsiniz.

Okuryazar programlama paradigması, [...] programların bilgisayar tarafından dayatılan şekilde ve sırada yazılmasını engeller ve bunun yerine programcıların düşüncelerinin mantığı ve akışı tarafından istenen sırada programlar geliştirmelerini sağlar. 2 Okuryazar programlar, sıradan bir insan dilinde, tıpkı bir deneme metni gibi kesintisiz bir mantık sergisi olarak yazılır [...].

Okuryazar programlama araçları okuryazar bir kaynak dosyadan iki gösterim elde etmek için kullanılır: biri bilgisayar tarafından daha fazla derleme veya yürütme, "karışık" kod, diğeri ise "dokumalı" olduğu söylenen biçimlendirilmiş belgeler olarak görüntülemek için uygundur okuryazarlık kaynağı.

Bir yan not ve örnek olarak: Yorum stilime uymamaya rağmen underscore.js JavaScript çerçevesi, iyi bir belgenin oldukça iyi bir örneğidir codebase ve iyi biçimlendirilmiş açıklamalı kaynak - API referansı olarak kullanmak en iyisi olsa da).


Bunlar kişisel sözleşmelerdir. Evet, garip olabilirim (ve sen de olabilirsin). Akranlarınızla çalışırken takımınızın kod kurallarına uyup uyduğunuz veya tercihlerine radikal bir şekilde saldırmadıkça ve birlikte yaşayın . Tarzınızın bir parçası ve sizi kodlayıcı (veya bir okulun takipçisi olarak tanımlayan) bir kodlama stili geliştirmek arasındaki ince çizgiyi bulmalısınız. bağlantınız olan düşünce veya organizasyon) ve bir grubun tutarlılık sözleşmesine saygı duyma .

17
haylem

Üniversiteye gittiğimde her zaman her kod satırına ve her yöntem başlığına yorum yapmam öğretildi. Hiç sorgulamadan yaptığınız ölçüde davul edildi/aşılandı. Farklı şirketlerde birçok Agile geliştirme ekibinin bir parçası olarak mavi ayda bir yorum yazabileceğimi söyleyebilirim.

Bunun nedeni iki kattır, her şeyden önce artık 101 farklı şey yapan uzun monolitik yöntemler yazmamalıyız, sınıf, yöntem ve değişken adları kendi kendini belgelemelidir. Örnek olarak aşağıdaki giriş yöntemini ele alalım.

public void Login(string username, string password)
{
    // Get the user entity
    var user = userRepository.GetUser(username);


    // Check that the user exists
    if (user == null)
    {
        throw new UserNotFoundException();
    }

    // Check that the users password matched
    if (user.HashedPassword != GetPasswordHash(password))
    {
        throw new InvalidUsernamePasswordException();
    }

    //Check that the users account has not expired
    if (user.Expired)
    {
        throw new UserExpiredException();
    }

    //Mark user as logged in
    ...
}

Bu, çok daha okunabilir ve belki de tekrar kullanılabilir bir şeye yeniden yazılabilir:

public void Login(string username, string password)
{
    var user = GetUserForUsername(username);

    CheckUsersPasswordMatched(user, password);

    CheckUserAccountNotExpired(user);

    MarkUserAsLoggedIn(user);
}

private void User GetUserForUsername(string username)
{
    var user = userRepository.GetUser(username);

    if (user == null)
    {
        throw new UserNotFoundException();
    }
    return user;
}

private void CheckUsersPasswordMatched(User user, string password)
{
    if (user.HashedPassword != GetPasswordHash(password))
    {
        throw new InvalidUsernamePasswordException();
    }
}

private void CheckUserAccountNotExpired(User user)
{
    if (user.Expired)
    {
        throw new UserExpiredException();
    }
}

Oturum açma yönteminden neler olup bittiğini açıkça görebilirsiniz. Bunu ekstra iş olarak görebilirsiniz, ancak yöntemleriniz küçüktür ve sadece bir işi vardır. Ayrıca yöntem adları açıklayıcıdır, bu nedenle herhangi bir yöntem başlığı yorumu yazmaya gerek yoktur. Çok fazla yöntemle karşılaşırsanız, bu, ilgili yöntemlerin UserAuthenticationService gibi başka bir nesneye yeniden faktörleştirilmesi gerektiğinin bir göstergesidir, bir nesnenin yalnızca bir işi olması gerektiğini unutmayın.

İkincisi, yorumlar da dahil olmak üzere yazdığınız her kod parçasının korunması gerekir, ne kadar çok yorumunuz varsa o kadar çok bakım yapmanız gerekir. Bir sınıfı veya değişkeni yeniden adlandırırsanız bir derleme hatası alırsınız, ancak kodun bir bölümünün çalışma şeklini değiştirir veya kaldırır ve ilgili yorumları güncellemezseniz, derleme hatası olmaz ve yorumlar karışıklığa neden olur. .

Eğer bir API yazıyorsanız, o zaman kamuya açık arayüzler, sınıflar, numaralandırmalar belgeleme için iyi yazılı başlık yorumları olması gerektiğine inanıyorum.

16
Bronumski

Biçime daha az, içeriğe daha fazla odaklanın. Örneğin, örneğinizdeki yorumlar bana yeni bir şey söylemiyor. Kod okumadan uzaklaştıkça değersizdirler ve bunlar gibi yorumlar en iyi şekilde, orijinal programcının yazdığı zaman ne yaptığını düşündüğü konusunda belirsiz bir referanstır. Kod örneğinden apply(Style) stili uyguladığınızı görebiliyorum, kaynağı okuyabiliyorum. Zihnini okuyamıyorum, - neden bunu yapıyorsun, yorum bana söylemeliydi.
Örneğin. ziyade

//Apply style.
Apply(style);

olmalı

// Unlike the others, this image needs to be drawn in the user-requested style 
apply(style);

Birçoğumuz mevcut kod üzerinde ekipler halinde çalışıyoruz, ekibin geri kalanını, zaten yapıldığını biçimlendiriyoruz. Tutarlılık güzelden çok daha önemlidir.

5
mattnz

Mümkün olduğunca kodunuzu yorumların tamamen yabancı olacağı şekilde yazın. Yalnızca kod, önemli bir kavramı açıkça ortaya koyacak şekilde yazılamadığında yorum ekleyin.

4
Dave
  1. doxygen gibi bir dokümantasyon sistemi seçin ve ona bağlı kalın. Üretilen belgeleri kontrol etmeye devam edin.
  2. Gelen kod tabanında yeni olan ve dokümanlarınızı okuyan birini resmetmeye çalışın, onunla çalışmaya başlayabilirler mi? Stajyerler aslında bunun için iyidir, mevcut doküman tabanınız ve basit bir görevinizle yeni bir tane oturun ve yanarlarsa, tekrar gitmelerini sağlamak için söylediğiniz her şeyin dokümanlarda ne kadar ilerlediğini görün.
  3. İnceleme işlemlerinizde dokümantasyon yorumlarını bir kontrol noktası haline getirin.
2
Kyrylo M

Benim tercihim bunu gerçekten basit tutmak. Her türlü süslü biçimlendirmeden kaçınırım. Bunun ana nedeni, kaynak kodunun en basit metin editörü ile rahatça düzenlenebilir olması gerektiğini düşünüyorum. Ayrıca metin paragraflarını asla sarmadım, bunun yerine editörün yumuşak sarma yapmasına izin verdim (satırsonu eklemeden).

2
Kyrylo M

Sık sık böyle yorumlar görürüm ve bazı araçlar otomatik olarak bu şekilde oluşturur:

/**
 * This is an example, how to waste vertical space,
 * and how to use useless asterixes.
 */

İki satır daha az:

/** This is an example, how to spare vertical space,
    and how to avoid useless asterixes. */

IDE'ler ve Editörler, not defteri seviyesinin biraz üzerinde, yorumları algılayıp farklı bir renkte basabiliyorlar. Çizginin başlangıcını asterixlerle süslemeye gerek yoktur.

Girinti için bir sekme kullanırsanız, bazı baytları bile yedeklersiniz.

Yorumu gri bir tonda yapan sofistike bir editör kullanmazsanız, büyük miktarda asterix vurgulamak için çalışır ve dikkatinizi çeker, bu da yapılacak doğru şeyin tersidir: geride kalmak.

2
user unknown

En önemli öneri:
Beklenmedik olanı yorumlayın, açık olanı değil!

Böyle bir yorum işe yaramaz:

// Adds a to b and write the result to c
c = a + b;

Sadece kodun söylediklerini tekrarlar ve kodu anlamayan insanlar için kod anlamıyorlar gibi yorum yazmamalısınız, herhangi bir kod okumazlar ve herhangi bir kod okumazlarsa, Yorumlarınızı da okumayın. Esas olarak, kodu anlayabildiğiniz kadar iyi anlayabilen diğer insanlar için yorum yazdığınızı unutmayın.

Bu nedenle, kodunuzun çoğu yorum gerektirmemelidir, çünkü kodunuzun çoğu yorum olmadan anlaşılamayacak kadar beceriksizse, kod veya kodlama stilinizle ilgili bir sorun vardır. Yorumlar kural değil istisna olmalıdır ve bu, yorumlarınızın stilinin kod stiliniz kadar önemli olmadığı anlamına gelir.

Kodunuzu, mantıksız olmayan yorum yapmak için yorum yaparken, bunları basit, kısa ve doğrudan noktaya tutmanızı tavsiye ederim. Bu tür yorumların dilbilgisi açısından doğru cümleler olması veya noktalama işaretleri kullanması bile gerekmez. Ek kod gibidirler, sadece derleyici için değil, insanlar için.

// Setting owners must happen on main thread
// and this function must not block
if (!info->owner) return errMissingOwner;

Bu nasıl iyi bir yorum? Sadece kodu okuyan bir programcı merak edebilir " Sahibi yoksa, neden bir hata döndürmek yerine sadece bir tane ayarlamıyorsunuz? " Yorum cevap veriyor : Çünkü ana iş parçacığı üzerinde olması gerekir ve bu ifade tek başına işlev muhtemelen ana iş parçacığı üzerinde çalışmıyor demektir. Tamam ama sonra bir programcı merak edebilir " Neden sadece ana iş parçacığına sevk değil? " ve yorum cevap veriyor: Fonksiyon engellememeli ve yapamıyorsunuz ana iş parçacığının şu anda ne yaptığından emin değilseniz engellemeyeceğini garanti eder. Bu nedenle yorum, kodun tek başına cevaplayamadığı tüm soruları yanıtlar ve bu cevapların hiçbiri açık değildir. Yorum sayesinde okuyucu, bir hatayla başarısız olmanın neden buradaki tek anlamlı seçenek olduğunu bilecek ve aynı zamanda koda dokunmak isteyen gelecekteki programcıların aptalca bir hata yapmamalarına yardımcı olacak.

Yine de asıl önemli yorumlar dokümantasyon amaçlı yorumlardır. Birisi yalnızca arayüzünüzü biliyor ancak uygulamayı bilmiyorsa, yorumlar kodunuzu doğru bir şekilde nasıl kullanacağınız ve hangi davranışı bekleyeceğiniz konusunda ek bilgi kaynağıdır. Bu yorumlar iyi okunabilir, genellikle tam cümleler olmalı ve doğru dilbilgisi ve noktalama işaretleri kullanmalıdır.

/// Sorts an integer array in place. 
/// The sorting algorithm is stable.
/// Sorting takes O(n * log2(n)) time 
/// and at most (n / 4) * sizeof(int) memory.
///
/// @param array The array to be sorted.
/// @param count Number of elements in the array.
///
/// @return @c false if memory allocation failed and
/// the array wasn't touched, @c true otherwise.
///
bool sortIntArray ( int * array, size_t count );

Bu yorum olmadan, bir programcı işlevin ne yaptığını ve parametrelerin ne anlama geldiğini tahmin edebilir, ancak sıralamanın kararlı olup olmadığını, zamana veya belleğe ne kadar bağlı olacağını veya hangi nedenle işlemin başarısız olabileceğini ve tam olarak ne olduğunu bilmek imkansızdır. başarısızlığın sonucu olacaktır.

2
Mecki

İşte benim iş kodu boyunca buldum bir "anti-desen": Yorum "değişiklik günlüğü" olarak kullanımı; sürüm kontrol sisteminizdeki günlük bunun içindir. Kod aşağıdaki gibi şeylerle doludur:

// 05-24-2011 (John Doe): Changed this method to use Foo class instead of Bar

ve genellikle yorumlanan eski kodu içerir (yine, bir VCS sisteminin noktasıdır, bu nedenle yeni kod yazıldıktan sonra kodda olması gerekmez). Kaçınılması gereken bir şey de "Buna neden ihtiyacımız var?" ya da daha da kötüsü, "Bu muhtemelen yeniden adlandırılmalıdır" (çünkü yeniden adlandırmak için karmaşık araçlar var, bu yüzden o yorumu yazmanız gerektiğinde şeyi yeniden adlandırmış olabilirsiniz). Yine, bu yorumların her ikisi ile düzenli olarak, aşağıdakiler doğrultusunda ilgileniyorum:

// (John Doe) 05-24-2011 not sure why we are using this object?
FooBar oFooBar = Quux.GetFooBar(iFooBarID, bSomeBool);
oFooBar.DiscombobulateBaz();

// (John Doe). This method is poorly named, it's used for more
// than just frazzling arvadents
public int FrazzleArvadent(int iArvadentID)
2
Wayne Molina

Biraz garip bir cevap ama en iyi yorum türü * yorum yok * .

Kodunuz açıksa, temiz ve dürüst:

[~ # ~] [~ # ~] yorumlara ihtiyacınız yok.

Yorumlar yalan ve bakımı zordur. (Google'da bunun hakkında konuşan birçok bağlantıdan biri)

Niyeti ipuçları için yönteminizi adlandırmaya çalışın, mümkün olduğunda tek sorumluluk ilkesi bağlı kalın ve kodunuz sinir bozucu yorumlara ihtiyaç duymadan bir esinti gibi okunacaktır.

(Bazı kod örnekleri için bronumski'nin cevabı konusuna bakın)

1
JeromeJ

Kod okuyucuları genellikle üç soruyu cevaplamaya çalışıyor:

  1. Bu sınıf veya işlev ne yapar? Bunu cevaplamak zorsa, o zaman çok fazla şey yapar. Belgelenmesi zor olan kod genellikle yanlıştır.
  2. Bunu nasıl kullanabilirim? Bir örnek yeterince iyi olabilir.
  3. Bu kod şaşırtıcı. Neden bunu yaptın? Büyük olasılıkla cevaplar: üçüncü taraf bileşenlerinde bir hata etrafında çalışmak, çünkü bariz tekniğin çok yavaş olduğu kanıtlandı

Diğer her şey kodda ifade edilmelidir. Nesir yazmak gibi, bu bir sanattır ve çok pratik gerektirir. Kodunuzun anlaşılabilir olup olmadığını bilmenin tek yolu, başkasının kodu okumasını sağlamaktır. Bir şeyi anlamadıklarında, sözlü olarak açıklamayın. Kodu geliştirin. Yorumları son çare olarak ekleyin.

"Çift uzunluk" görürsem "Ölçüm birimi nedir?" Yorum eklemeyin. Değişken adını değiştirin. Bir kod bloğu görürsem ve "bu ne işe yarar?" Dersem, yorum eklemeyin. Anlamlı bir ada sahip bir işlev ayıklayın. Bir işlevi 17 bağımsız değişkene ihtiyaç duyacağı için çıkaramazsanız, kodu yeniden düzenleyin.

1
kevin cline