İlgili koddan önce veya sonra yorum yapın [kapalı]

Bir yorumun, geçerli olduğu çizgiye sığmayacağını (veya gidemeyeceğini varsayalım), yorumdan önce koddan önce mi yoksa sonra mı yazmalı?

Gelecekteki okuyucular nerede olursa, yorumun kapsamını en iyi şekilde anlayacaklardır. Diğer bir deyişle, çoğu programcı / senaryo yazarı nerede olursa olsun böyle yorumlar yapmıştır.

Peki , çoğu programcı / script nerede bir yorum yazıyor: kodundan önce mi yoksa sonra mı?

Cevabınız sadece belirli diller için geçerliyse, lütfen hangisini belirtin.

Ve cevabınızı destekleyen kabul edilmiş bir spesifikasyon veya kılavuzu alıntı yapabilirseniz, çok daha iyi.

Satır içi ya da yorumun uygulanması gereken koddan önce yorum yaparım. Yorumların anlamı, kodun kendisini okumaya gerek kalmadan kodun ne yaptığını biraz anlamaktır. Bu nedenle, açıklamaları, tanımladığı kodun önüne yerleştirmek çok daha anlamlı olur.

Microsoft, prosedürlere küçük bir yorum ile başlamanın iyi bir programlama uygulaması olacağını söyledi. (Prosedürlerden sonra yorum yapmaktan bahsetmiyorlar) MSDN Link VisualBasic ile ilgili, ancak sanırım en çok programlama dili için geçerli.

Yönlendirdikleri kodun üstünde yorum yapmayı tercih ediyorum, sadece bir kişiye kod okuyan bir kodun daha karmaşık olduğunu belirten bazı kod satırlarının sabit olduğunu açıklamak için önceki koda başvurmaya çalışmak yerine, kodun ne olduğuna dair bir kod okuma daha mantıklı geliyor. öyleyse dokunma.

Kod genel olarak yukarıdan aşağıya okunur. Başka bir şey olmazsa, kas hafızası bir yorumu bir sonraki kod satırıyla ilişkilendirmeme neden olur.

Tipik olarak, yorum, işle aynı girintiyi izleyen satırın tepesinde olmalıdır. Örneğin, fonksiyonların gövdesinin üstündeki yorumlar ve bir liner kritik bir algoritmanın başlamasının hemen üzerinde yorumlar.

Bunun nedeni, birileri okumaya başladığında, bir şeyin neden bu şekilde yapıldığına dair açık bir soru ortaya çıkıyor; kişinin cevabı bulmak için hangi noktaya kadar kaydırma yapması gerektiğini bilmemesi. Üstte ise, görmek için orada.

Peki, çoğu programcı / script nerede bir yorum yazıyor: kodundan önce mi yoksa sonra mı?

Yıllarca çeşitli dilleri kullanarak programlama yaparak, herhangi bir dilde herhangi bir kodun yorum yaptığı koddan sonra yeni bir satıra konduğunu hatırlamıyorum . ABD'de, en azından, fiili standart ya kodtan önce ya da kodu izleyen aynı satırda yorum yapmaktadır. İlgili koddan sonra yorumlarınızı yazmak bir uyuşturucu testi, bir psikiyatrik değerlendirme ve / veya bir çift pense ve bir el feneri ile bir tarih davet eder.

Düşünebildiğim tek istisna, daha önce yorumlanmış bir bölümün sonunu gösteren bir yorumdur, şunun gibi:

// BEGIN CRITICAL SECTION
lock(&myMutex);

doSomeThreadUnsafeStuff();

unlock(&myMutex);
// END CRITICAL SECTION

Jef Raskin, okumaya değer yorumlar üzerine iyi düşünülmüş bir makale yazdı . Yorumlarını koddan önce mi yoksa sonra mı koyduğunu söylemez, ancak hiçbir zaman satır içi koyamadığını söyler ve ben de onlardan sonra koymadığı çok fazla para koyarım.

Sadece gerçekten gerekli olan yerlerde yorum yapmaya çalışın; Kod mümkün olduğunda kendi kendini belgelendirmeye çalışmalıdır.

Olduğu söyleniyor, yerleşim bağlı olabilir: Yorum için ayrı bir satır kullanırsanız , gerçek kodun önüne koyun . Aynı çizgide varsa, sonra koyun.

// this workaround is required to make the compiler happy
int i = 0;

Vs.

int i = 0; // make the compiler happy

Ama asla:

int i = 0;
// this workaround is required to make the compiler happy

Ben aslında yorumların büyük bir hayranı değilim. Bir yazılım mühendisliği kursu sırasında, kendi kendini belgeleyen kod fikri ile tanıştım. Kod, yalnızca% 100 garantili doğru belgenin belgelenmesidir - yorumların güncellenmesi, dikkatle yapılandırılması ve uygun olması gerekir, aksi halde yorum yapmamaktan daha kötü olabilecek tuzaklardır. Bir C ++ mağazasında katı bir stil rehberi ve anlamlı adlandırma kuralları ile çalışmaya başladım ve bu kavramı gerçekten içselleştirmedim.

Bazen yorumlar gerekli olabilir. Çoğu zaman, dikkatli değişken isimlendirme, beyaz alan ve gruplamanın anlamlı bir şekilde kullanılması ve kodun anlamlı bir mantıksal organizasyonu yorum gereksinimini ortadan kaldırır.

Bu gerçekten, sorunuzun cevabının aksine, bahanenizin bahanesinin ve geçerliliğinin ihmalidir. Hala bunun konuyla alakalı olduğunu ve sana yardımcı olabileceğini düşünüyorum ve ben bir pislik değildim. Olmazsa, -1'ler bana hakim olacak.

Yorumun kodun önünde görünmesi, okuyucunun karşılaşmak üzere oldukları kod için bir bağlam oluşturmasına yardımcı olur. Kodu onlara atmaktan ve kafanın karışmasından sonra açıklamaktan çok daha insancıl.

Tamam, "after" durumunu yapacağım: kod her zaman birincil dokümantasyon olmalıdır, yorum ise (anlamsal bir anlamı yoktur) parantez içindeki bir açıklama gibidir. Bu nedenle, yorumu açıklama gerektiren kodun altına koymak, kodu asıl açıklama olarak bırakır ve açıklama için sadece açıklama kullanır. Örneğin,

if(date == CHRISTMAS){
     //Deliver presents
     val (nice, naughty) = partition(boysAndGirls);
     prepSled();
     findRudolph();
     putOnRedSuit();
     ...
}else{
     //Not Christmas, build toys
     monitorElves();
     ...
}

Yorumu testten önce koyarsanız, okuyucu yorumu ana öncelik olarak okumaya meyillidir ve yanlış yönlendirildiklerinin farkında olmadan kodu yakından okuyamayabilir:

 //Check to see if it's a leap year
 if(year % 4 == 0){ ... }  

Bazı fikirleri teknik yazıdan (en azından İngilizce dilinde) ödünç almak için, notlar veya uyarı uyarıları gibi şeyler genellikle not veya uyarı uyarısının uygulandığı talimat veya bölümden önce yerleştirilir.

Neden kodun bir teknik yazı biçimi olarak değerlendirilemediğini anlamıyorum - her blok bir talimattır. İngilizce dili gibi, çoğu programlama dili soldan sağa, yukarıdan aşağıya okunur. Yorumlar kodla ilgili notlardır - düzeltilecek hataları veya gelecekteki bir geliştiricinin bilmesi gereken şeyleri tanımlayabilirler.

Bu ilişkiyi takiben, yorumu, ifade ettiği kod bloğunun üstüne koymak daha uygun görünmektedir.

Bir yorumun, ne tür bir yorum olduğuna bağlı olarak, bir kod parçasının üstüne veya altına gitmesi gerekebilir: Kodun ne yaptığı hakkında çok kısa bir açıklama yaparsa, kodun önüne geçmesi gerekir; Kodun nasıl çalıştığıyla ilgili teknik bir ayrıntıyı ayrıntılı olarak açıklığa kavuşturursa, kodu takip etmesi gerekir.

Neyse ki, bir yorum bir kod parçasının üstüne ya da altına gidebilir ve yine de boş satırları uygun şekilde kullanarak hangi kod parçasına ait olduğuna dair hiçbir şüphe bırakmaz. Tabii ki, boş satırların kullanımına dikkat etmeyen programcılar neden bahsettiğimi bilmeyecekler; onlardan biriyseniz, lütfen bu cevabı atlayın ve yaşamınıza devam edin. Ancak boş satırlara dikkat eden programcılar, boş satırların kodu mantıksal varlıklara bölmek için kullanıldığını çok iyi biliyorlar. Yani, aşağıdakileri görürseniz:

[blank line]
/* comment */
{ code }
[blank line]

Yorumun koda ait olduğunu ve kodun ne yaptığını söylediğini biliyorsunuz. Oysa eğer aşağıdakileri görürseniz:

[blank line]
{ code }
/* comment */
[blank line]

Yine, yorumun bu koda ait olduğunu çok iyi biliyorsunuz ve kodun yaptığı şeyi nasıl yaptığıyla ilgili bir açıklama.

Yukarıdaki yorumlar en iyisidir.

yorumları eklemek zorundaysanız ve kodunuz açıklayıcı değilse, o zaman bir kod bloğu ile karıştırılmamayı tercih ederim, o zaman "ahh, yapması gereken buydu" bölümüne bakın.

Kod "kendi kendini belgeleyebilir" olabilir (ve olmalıdır), ancak bir yöntemin nasıl çalıştığını anlamak için her kod satırını okuyup anlamanız gerekiyorsa. If a summary/ comment found in the last of method then it will be lot of coding time is spent searching for the chunk of code that we wish to edit. By using a summary comment on each block, I can quickly zero in on the block that is relevant to my task.

Bu konu hakkında konuştuğumda, çoğu bilgisayar tarafından okunabilen dokümantasyon sisteminin (Doc XML, Doxygen, Java doc vb.) Yorumların ilgili koddan önce gelmesini beklediğini gördüm - bu standartla uyumlu kalmak daha iyidir.

SO konusuna da katılıyorum - Önceden değil, kod bloklarından sonra yorumlar ekleyelim mi? ..

Ben de önünü bilmek isterdim ...

Yorumları (çoğu zaman benim tarafımdan yazdığı gibi) izleme düzeyi günlük ifadelerine sık sık dönüştürürüm. Bu genellikle nereye yerleştirileceğini anlamayı çok daha kolaylaştırır.

    // Return an empty list if we failed to retrieve anything
    // I convert above to:
    logger.trace("Return an empty list if we failed to retrieve anything");

Ek bir avantaj, zorlaştığında kütük izlemeyi açıp daha ayrıntılı yürütme kütüğü alabilmemdir.