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

İnşallah bu soru, herkesin öğrenebileceği faydalı bir şey olan en ilginç tavsiye ve önerileri toplayacaktır.

Tamam başlayacağım.

1. Genellikle, /* */çok fazla satır yorum yapmam gerekse bile yorumları kullanmam .

   Avantajları : Kod, görsel olarak böyle bir 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 yorumlayabilme özelliğine sahiptir ve genellikle tek satırlık sözdizimi ile yaparlar.

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

2. Bitmiş bir yorumun sonuna "nokta" koyun.

   Ö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ı sadece bitirdiğiniz yorumlara yerleştirin. Bazen geçici bilgiler yazabilirsiniz, bu yüzden "nokta" eksikliği size geri dönmek ve bu yoruma bazı metinler eklemek istediğinizi söyleyecektir.

3. Numaralandırmalardaki metni hizalama, parametreleri yorumlama vb.

   Ö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 için sadece daha iyi ve görsel olarak daha kolay görünür.

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

4. Kod yazarak elde edemediğiniz bir yorum yazın.

   Örneğin, aptal yorum:

   //Apply style.
   Apply(style);
   

   Avantajları : Yorumlarda sadece faydalı bilgiler içeren açık ve küçük kodlara sahip olacaksınız.

Aşağıdaki ifadelerin bazıları, bazı gerekçelerle de olsa oldukça kişiseldir ve bu şekilde olması amaçlanmıştır.

Yorum Türleri

Kısa versiyon için ... Şunun için yorum kullandım:

• veri yapılarında alanları açıklayan izleyen yorumlar (bunlardan başka tek satır yorumlar yapmıyorum)
• blokların üzerinde 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) sebepler için aşağıyı okuyun.

İzleyen Yorumlar

Dile bağlı olarak, tek satırlı yorumlar veya çok satırlı yorumlar kullanarak. Neden buna bağlı? Bu sadece bir standardizasyon sorunu. C kodunu yazarken, eski moda ANSI C89 kodunu varsayılan olarak tercih ediyorum, bu yüzden daima sahip olmayı tercih ederim /* comments */.

Bu nedenle, çoğu zaman C'de olur ve bazen C benzeri bir sözdizimi olan diller için (kod tabanının tarzına bağlıdır):

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

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

Dil tek satırlı yorumları destekliyorsa ve C tabanlı değilse, tek satırlı yorumları kullanmaya daha fazla hevesliyim. Aksi takdirde, korkarım şimdi alışkanlık aldım. Bu mutlaka kötü değil, çünkü özlü olmaya zorluyor.

Çok Hatlı Yorumlar

Bunun için tek satırlı yorumlar kullanmaktan kesinlikle vazgeçtim, bunun için görsel olarak daha çekici. 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.
 */

Veya bu (ama kişisel kod temeli dışında veya çoğunlukla telif hakkı bildirimleri dışında pek fazla bir şey yapmam - bu benim için tarihseldir ve eğitim geçmişimden gelir. Ne yazık ki, çoğu IDE otomatik formatı kullanırken bunu mahveder) :

/*
** 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 de gerekirse, izleyen yorumlar için daha önce söylediklerimi kullanarak satır içi yorum yapardım, eğer izleyen bir konumda kullanmak mantıklıysa. Çok özel bir dönüş durumunda günü, örneğin, ya da belge a kadar switch'ın caseifadeleri (nadir, ben kullanımı genellikle geçmiyoruz), ya da ben bir şube belgelemek zaman if ... elsekontrol akışı. Eğer bunlardan biri değilse, genellikle fonksiyon / yöntem / blok adımlarını gösteren kapsam dışında bir yorum bloğu benim için daha anlamlı olur.

Bunları istisnai olarak kullanırım, dokümantasyon yorumlarını desteklemeyen bir dilde kodlama dışında (aşağıya bakınız); bu durumda daha yaygın hale gelirler. Ancak genel durumda, bu sadece diğer geliştiricilere yönelik olan şeyleri belgelemek içindir ve gerçekten öne çıkması gereken dahili yorumlardır. Örneğin, bir "zorunlu" catchblok 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 zaten benim için çirkin ama bazı durumlarda tahammül edeceğim.

Belge Yorumları

Javadoc ve ark.

Bunları genellikle bir genel API için geçerliyse bir özellik tanıtan (veya değiştiren) sürümleri belgelemek ve bazı örnekler sunmak için (net giriş ve çıkış durumları ve özel durumlar ile) bunları genellikle yöntemler ve sınıflar üzerinde kullanırdım. Her ne kadar bazı durumlarda bir ünite vakası bunları belgelemek daha iyi olsa da, ünite testleri mutlaka insan tarafından okunabilir değildir (hangi DSL kullanımını kullanırsanız kullanın).

Bunun için takip eden yorumları tercih ettiğim için alanların / özelliklerin belgelenmesi konusunda beni biraz rahatsız ediyorlar ve dokümantasyon oluşturma çerçevesinin tamamı dokümantasyon yorumlarını desteklemiyor. Doxygen, örneğin, fakat JavaDoc yapmıyor, bu da tüm alanlarınız için bir üst yoruma ihtiyaç duyduğunuz anlamına geliyor. Yine de, Java çizgileri çoğu zaman göreceli olarak uzun olduğu için hayatta kalabiliyorum, bu yüzden takip eden bir yorum, çizgiyi tolerans eşiğimin ötesine uzatarak beni eşit derecede korkuturdu. Javadoc bunu geliştirmeyi düşünürse, ben daha mutlu olurdum.

Yorumlanan Kod

Tek satırlık yalnızca bir nedenden ötürü, C-benzeri dillerde (katı C için derleme dışında, onları gerçekten kullanmadığım yerler hariç) kullanıyorum: kodlama sırasında bir şeyler yorumlamak için. Çoğu IDE'nin tek satırlık yorumlar için geçiş yapması gerekir (girinti veya sütun 0 ile aynı hizada) ve bu benim için durum için uygun. Çok satırlı yorumlar için geçişi kullanmak (veya satırların ortasındaki bazı IDE'ler için seçmek) yorum / yorum arasında kolayca geçiş yapmayı zorlaştırır.

Ancak SCM'deki yorum koduna karşı olduğum için, genellikle çok kısa sürdü çünkü taahhütte bulunmadan önce yorumlanan parçaları sileceğim. ( Bu soruya cevabımı "yorumlar doğrultusunda ve SCM'lerde düzenlendi" ) oku.

Yorum Stilleri

Genelde yazma eğilimindedir:

• Daha sonra bir API belgesinde veya hatta üretilen bir el kitabının bir parçası olarak okunması gerektiği gibi, dokümantasyon yorumları için doğru dilbilgisi (noktalama işaretleri dahil) ile cümleleri tamamlayın.
• iyi biçimlendirilmiş ancak çok satırlı yorum blokları için noktalama işaretleri / büyük harfler üzerinde daha fazla gevşek
• noktalama işaretsiz bloklar (boşluk nedeniyle ve genellikle yorum parantezli bir ifadeye benzer şekilde okunan kısa olduğu için)

Okuryazar Programlama Üzerine Bir Not

Donald Knuth'un bu makalesinde anlatıldığı gibi , Literatür Programlaması ile ilgilenmek isteyebilirsiniz .

Okuryazar programlama paradigması, [...], programların bilgisayar tarafından emredildiği biçimde ve sırayla program yazma sürecinden uzaklaştığını ve bunun yerine programcıların düşüncelerinin mantığı ve akışının talep ettiği sırada programlar geliştirmesini sağlar. 2 Literatür programları, bir makalenin metni gibi, sıradan bir insan dilinde kesintisiz bir mantık sunumu olarak yazılmıştı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 için uygun, "karışık" kod ve diğeri de "dokumasız" olduğu söylenen biçimlendirilmiş belgeler olarak görüntülemek için uygundur. okuryazar kaynak.

Bir yan not ve örnek olarak: underscore.js benim yorum yapma tarzı ile uyumsuzluk rağmen, JavaScript çerçevesi, iyi belge oldukça iyi bir örnektir kod tabanı ve iyi oluşturulmuş açıklamalı kaynağı - gerçi belki iyi olarak kullanmak bir API referansı).

Bunlar kişisel sözleşmeler. Evet, tuhaf olabilirim (ve siz de olabilirsiniz). It yolundaysa, sürece kadar takip edip ekibinizin kod sözleşmelere uymak yaşıtları ile çalışırken veya kökten tercihlerini saldırmayın ve cohabitate güzel. Tarzınızın bir parçası ve sizi kodlayıcı olarak tanımlayan (veya bağlantı kurduğunuz bir düşünce veya organizasyon okulunun takipçisi olarak) bir kodlama stili geliştirmek ile bir grubun tutarlılık sözleşmesine saygı duymak arasındaki ince çizgiyi bulmalısınız. .

Üniversiteye gittiğimde her zaman her kod satırını ve her yöntem başlığını yorumlamam öğretildi. Sorunuz olmadan yaptığınız ölçüde batırıldı / indoktlandı. Farklı şirketlerdeki birkaç Çevik geliştirme ekibinin bir parçası olduğumu söyleyebilirim, bir ay içinde bir kez yorum yazabileceğimi söyleyebilirim.

Bunun nedeni iki katlıdır, her şeyden önce 101 farklı şey yapan uzun monolitik yöntemler yazmamalıyız, sınıf, yöntem ve değişken isimleri kendi kendini belgelemeli olmalıdır. Aşağıdaki giriş yöntemini örnek olarak alın.

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 okunaklı ve belki de tekrar kullanılabilir bir şey için 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();
    }
}

Ne olup bittiğini giriş yönteminden açıkça görebilirsiniz. Bunu fazladan bir iş olarak görebilirsiniz, ancak yöntemleriniz küçük ve sadece bir iş var. Ek olarak, yöntem adları tanımlayı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 yansıtılması 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 muhafaza edilmesi gerekir, ne kadar çok yorumunuz varsa o kadar korunur. Bir sınıfı veya değişkeni yeniden adlandırırsanız bir derleme hatası alırsınız ancak bir kod bölümünün çalışma biçimini değiştirir veya kaldırır ve ilgili yorumları güncellemezseniz derleme hatası olmaz ve yorumlar karışıklığa neden olur .

Bir API yazıyorsanız, halka açık arayüzler, sınıflar, numaralandırmaların dokümantasyon için iyi yazılmış başlık yorumları olması gerektiğine inanıyorum.

Biçime daha az ve içeriğe daha çok odaklanın. Mesela, sizdeki örneğindeki yorumlar bana yeni bir şey söyleme Okuma kodundan mahrum kaldıklarından daha değersizler ve bunlar gibi yorumlar en iyi ihtimalle orijinal programcının yazdığı sırada ne yaptığını düşündüğü belirsiz bir referans. Kod örneğinden uyguladığınız bir "uygulama (Stil)" uyguladığınızı görebiliyorum, kaynak okuyabiliyorum. Zihnini okuyamıyorum, - neden yorum yapıyorsun? örneğin

//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 kodla takımlar halinde çalışırız, ekibin geri kalanını, zaten yapıldığı şekilde biçimlendirin. Güzel olmaktan çok daha önemli olan tutarlılık.

Mümkün olduğu kadar kodunuzu, yorumlarınızı tamamen gereksiz hale getirecek şekilde yazın. Yalnızca kod, önemli bir kavramı açıkça ortaya koyacak şekilde yazılamadığında yorumlar ekleyin.

Benim tercihim onu ​​gerçekten basit tutmak. Her türlü fantezi biçiminden kaçınıyorum. Bunun ana nedeni kaynak kodunun en basit metin editörüyle bile rahatça düzenlenebilir olması gerektiğini düşünüyorum. Ayrıca, metin paragraflarını asla zorlamıyorum ama bunun yerine, editörün yumuşak kaydırma yapmasına izin verdim (yeni satır eklemesi yok).

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

/** 
 * 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 çok üstünde, yorumları tespit edebiliyor ve farklı bir renkte basabiliyor. Çizginin başlangıcını yıldız işaretleriyle süslemeye gerek yoktur.

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

Yorumu gri tonda düzenleyen karmaşık bir düzenleyici kullanmazsanız, büyük miktarda asteriks vurgulamak için çalışacak ve dikkatinizi çekecektir; bu yapılacak doğru şeyin zıttıdır: geride kalmak.

İşte işim kodunda bulduğum bir "anti-pattern": Yorumların "değişiklik günlüğü" olarak kullanılması; sürüm kontrol sisteminizdeki günlük bunun içindir. Kod şöyle şeyler ile çevrili:

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

ve genellikle genellikle yorumlanmış eski kodu içerir (yine, bu bir VCS sisteminin amacı bu yüzden yeni kod yazıldıktan sonra kodda olması gerekmez). Ayrıca kaçınılması gereken bir şey de "Neden buna ihtiyacımız var?" veya daha da kötüsü, "Bu muhtemelen yeniden adlandırılmalıdır" (çünkü yeniden adlandırma için karmaşık araçlar vardır, bu nedenle, söz konusu adımı yeniden adlandırabileceğiniz bu yorumu yazmanız zaman aldı). Yine, bu yorumların her ikisini de düzenli olarak şu satırlarla ele alıyorum:

// (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)

1. Doxygen gibi bir dokümantasyon sistemi seçin ve ona bağlı kalın . Üretilen belgeleri kontrol etmeye devam edin.
2. Kod tabanında yeni birisinin geldiğini ve dokümanlarınızı okuduğunu hayal etmeye çalışın, buna başlayabilirler mi? Stajyerler aslında bunun için iyi, mevcut belge tabanınızla ve basit bir görevle yeni bir tanesine oturun ve ne kadar uzağa gittiklerini görün, eğer tökezlerlerse, onlara tekrar gitmelerini sağlamak için söylediğiniz herhangi bir şeyden emin olabilirsiniz.
3. Belgelendirme yorumlarınızı inceleme işleminizde bir denetim noktası yapın.

Kod okuyucuları genellikle üç soruyu yanıtlamaya çalışır:

1. Bu sınıf veya işlev ne yapar? Bu cevap vermek zorsa, o zaman çok fazla 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? En muhtemel cevaplar: Üçüncü taraf bileşenlerinde bir hata etrafında çalışmak, çünkü bariz teknik çok yavaş oldu.

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

Eğer "ç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 yapar?" Derim, yorum eklemeyin. Anlamlı bir ada sahip bir işlevi çıkarın. 17 argümana ihtiyaç duyacağından bir fonksiyonu çıkaramazsanız, kodu yeniden aktive edin.