“Yorumlar bir kod kokusu” [kapalı]

Bir iş arkadaşım kod içi yorumların herhangi bir kullanımının (yani, javadoc tarzı yöntem veya sınıf yorumları değil) kod kokusu olduğuna inanıyor . Ne düşünüyorsun?

Yalnızca yorum kodun ne yaptığını açıklarsa.

Bir yöntemde veya blokta neler olduğunu bilmek istesem kodu okurdum. Neyse, yine de, belirli bir proje üzerinde çalışan geliştiricilerin, en azından ne yazıldığını okumak ve ne yaptığını anlamak için geliştirme dili ile aşina olduklarını umardım.

Bazı aşırı optimizasyon durumlarında, birinin kodunuzun ne yaptığını izlemesini zorlaştıran teknikler kullanıyor olabilirsiniz. Bu durumlarda, yorumlar yalnızca neden bu tür optimizasyonlara sahip olduğunuzu değil aynı zamanda kodun ne yaptığını açıklamak için de kullanılabilir ve kullanılmalıdır. İyi bir kural, uygulama diline ve projeye aşina bir başkasının (veya diğer birçok kişinin) kodunuza bakmasını sağlamaktır - eğer hem nedenini hem de nasıl olduğunu anlayamıyorlarsa, hem nedenini hem de nedenini yorumlamalısınız. nasıl.

Ancak, kodda açık olmayan şey, neden bir şey yaptığınızdır. Başkaları için açık olmayan bir yaklaşım izlerseniz, verdiğiniz kararları neden verdiğinizi açıklayan bir yorumunuz olmalıdır. İnsanların Y yerine neden X yaptığını bilmek isteyen bir kod incelemesinden sonraya kadar bir yoruma ihtiyaç duyulduğunu bile bilmiyor olabilirsiniz; cevabınızı koddaki herkes için kodda bulabilirsiniz. gelecekte.

En önemlisi, kodunuzu değiştirdiğinizde yorumlarınızı değiştirmektir. Bir algoritmayı değiştirirseniz, Y'yi neden X algoritmasıyla kullandığınızla ilgili yorumları güncellediğinizden emin olun. Eski yorumlar daha da büyük bir kod kokusudur.

Bu şu anda duymak için özellikle rahatsız edici, bu hafta sonu biraz zaman harcadım, bir araştırma algoritması (aslında yayınlanmayan bir tane) uygulayan çok iyi adlandırılmış, açık kodlu kodlara bakarak geçirdim. Ben çok tanıdık biriyim, yanımda oturan adam muciddi ve kod birkaç yıl önce başkaları tarafından yazılmıştı. Bunu zorlukla takip edebiliriz .

İş arkadaşınız yeterince açık değil.

Yorumlar nedenini değil nedenini açıklamalıdır.

Howtür yorumları genellikle yeniden yönlendirme kullanarak daha iyi anlaşılır. Şahsen ben genellikle yeniden yapılanma lehine yorumlar yapmaktan kaçınırım.

Önce:

# convert to cents
a = x * 100

# avg cents per customer 
avg = a / n

# add to list
avgs < avg
t += 1

sonra:

total_cents = total * 100
average_per_customer = total_cents / customer_count

track_average(average_per_customer)

İş arkadaşını sapık ilan ediyorum! Heretik yakıcı botlarım nerede?

Obsesif yorumlama kötüdür ve bakım başağrısıdır ve yorumlar, iyi adlandırılmış yöntemlerin, sınıfların, değişkenlerin vs. yerine geçmez. Ancak bazen, bir şeyi neden olduğu şekilde koymak , kodu korumak zorunda olan zavallı salak için son derece değerli olabilir. altı ay içinde - özellikle de bu zavallı aptal sen olduğun için çok rüzgârlı.

Üzerinde çalıştığım koddan bazı gerçek yorumlar:

    // If this happens, somebody's been screwing around with the database definitions and
    // has removed the restriction that a given alarm may have only one entry in the 
    // notifications table.  Bad maintenance programmer!  Bad!  No biscuit!



    // If an alert is active on our side but inactive on theirs, that might mean
    // they closed the alert.  (Or that we just haven't told them about it yet.)  The
    // logic comes later; for now, we'll just compile it in a list.



    // If we know for a fact that an alarm isn't getting through, we're going to whine pretty
    // aggressively about it until it gets fixed.

İdeal olarak, kod o kadar iyi kodlanmalı ki otomatik açıklayıcı olmalıdır. Gerçek dünyada, çok yüksek kalitede kodun bazen yorum gerektirdiğini biliyoruz.

Kesinlikle kaçınmanız gereken "yorum kodu artıklığı" (koda hiçbir şey eklemeyen yorumlar):

i++; // Increment i by 1

Sonra, iyi (ve korunmuş / hizalı) bir kod tasarımı ve dokümantasyonu varsa, yorum yapmak daha da faydalı olacaktır.

Ancak bazı durumlarda yorumlar kod okunabilirliğinde iyi bir yardımcı olabilir:

while( foo )
{
     if( dummy )
     {
     }
     else // !dummy
     {
     }
} // end while( foo )

Unutmayın, senkronize etmek ve yorumlarda da devam etmek zorundasınız. Ayrıca eski ya da yanlış yorumlar korkunç bir acı olabilir! Genel bir kural olarak, çok fazla yorum yapmak kötü programlamanın bir belirtisi olabilir.

Bir yöntemi veya işlemi "kod kokusu" olarak tanımlamak, "zealotry kokusu" dur. Terim yeni "zararlı olarak kabul edilir" hale geliyor.

Lütfen, bu tür şeylerin kurallar olması gerektiğini unutmayın.

Diğer cevapların çoğu, yorum yapılmasının ne zaman gerektiği konusunda iyi tavsiyeler verir.

Şahsen çok az yorum kullanıyorum. Belirsiz işlemlerin amacını açıklayın ve zaman zaman ölüm tehdidini, haftalar sürmesi gereken işleri kendi başlarına değiştirmeyi düşünen herkese bırakın.

Bir anaokulu öğrenene kadar her şeyi yeniden düzenlemek muhtemelen zamanınızın verimli bir şekilde kullanılmaması ve muhtemelen daha kısa ve öz bir versiyonun yerine geçmeyecektir.

Yorumlar çalışma süresini etkilemez, bu nedenle dikkate alınması gereken tek olumsuz konu bakımdır.

Bazı durumlarda, hiçbir iyi adlandırma, yeniden düzenleme vb. Hiçbir yorum yapamaz. Sadece bu gerçek dünya örneğine bakın (dil Groovy'dir):

  response.contentType="text/html"
  render '{"success":true}'

Garip görünüyor, değil mi? Muhtemelen bir kopyala-yapıştır hatası? Bir hata düzeltme için ağlıyor?

Şimdi yorumlarla aynı:

  // DO NOT TOUCH THE FOLLOWING TWO LINES; the ExtJS UploadForm requires it exactly like that!!!
  response.contentType="text/html"  // must be text/html so the browser renders the response within the invisible iframe, where ExtJS can access it
  render '{"success":true}'         // ExtJS expects that, otherwise it will call the failure handler instead of the succss handler

Buradaki ana sorun "kod kokusu" teriminin anlamıdır.

Pek çok insan (siz dahil, sanırım) bir hataya yakın bir şey veya en azından düzeltilmesi gereken bir şey olarak bir kod kokusunu anlıyor. Belki de bunu "anti-patern" ile eşanlamlı olarak düşünürsünüz.

Bu terimin anlamı değil!

Kod kokusu metaforu Wards Wiki'den geliyor ve şu vurguyu yapıyorlar:

Bir CodeSmell'in bir şeylerin kesin olamayacağının yanlış olabileceğine dair bir ipucu olduğunu unutmayın. Mükemmel bir deyim CodeSmell olarak düşünülebilir, çünkü çoğu zaman yanlış kullanılır veya çoğu durumda işe yarayan daha basit bir alternatif vardır. Bir şeye CodeSmell demek bir saldırı değildir; bu sadece daha yakından bakmak garanti edildiğinin bir işareti.

Öyleyse, yorumların kod kokusu olduğu ne anlama geliyor: bir yorum gördüğünüzde duraklatmanız ve düşünmeniz gerektiği anlamına gelir: "Hmm, bir şeyin iyileştirilebileceğine dair bir ipucu hissediyorum". Belki bir değişkeni yeniden adlandırabilir, "özütleme yöntemi" -refactoring gerçekleştirebilirsiniz - veya belki de yorum aslında en iyi çözümdür.

Yorumların kod kokusu almasının anlamı budur.

EDIT: Ben sadece benden daha iyi açıklayan bu iki makaleye rastladım:

• Koddaki Özürler
• Yorumlara İhtiyaç Var

Kuralın oldukça basit olduğunu düşünüyorum: kodunuzu gören tamamen yabancı bir insan hayal edin. Muhtemelen 5 yıl içinde kendi koduna yabancı olacaksın. Bu yabancı için kodunuzu anlamak için zihinsel çabayı en aza indirmeye çalışın.

Doğru yorumlara sahip olmak iyi bir fikir yorum yazmaya başlamaktır.

// This function will do something with the parameters, 
// the parameters should be good according to some rules.
myFunction(parameters)
{
    // It will do some things to get started.

    // It will do more with the stuff.

    // It will end doing things with the stuff.
}

Bu, yorumlardan bile kolayca kurtulabileceğiniz yöntemleri ayıklamanıza olanak tanır,
sadece kodun bunları söylemesine izin verin ! Bunun nasıl yazıldığını (kes / yapıştır) çok güzel bir şekilde görün:

// This function will do something with the parameters, 
// the parameters should be good according to some rules.
myfunction(parameters)
{
  var someThing = initializedWithSomething;

  doSomethingWith(someThing);

  doMoreWith(someThing);

  endDoingThingsWith(someThing);

  return someThing;
}

// This function will do some things to get started,
// the parameters should be good according to some rules.
doSomethingWith(parameters)
{
  parameters.manipulateInSomeWay();
  ... etc ...
}

... etc ...

Ayrılamayacak şeyler için sadece metotları çıkarmayın ve yorumları yorumların altına yazın.

Bu, yorumu en aza indirmenin yararlı bir yolu olarak görüyorum, her bir çizgiyi yorumlamaya gitmek gerçekten işe yaramaz ... Sadece bir sihirli değer başlatmasıyla ilgili veya mantıklı olduğu durumlarda tek bir satırı belgeleyin.

Parametreler çok fazla kullanılıyorsa, sınıfınızdaki özel üyeler olmalıdır.

Bence cevap her zamanki "Bağımlı" dır. Yorum kodu sadece yorum kodu için bir koku. Kodun yorumlanması, çünkü bir büyüklük sırası daha hızlı bir şekilde belirsiz bir algoritma kullanıyorsanız, bakım programlayıcısından (genellikle yazdıktan 6 ay sonra) ne yaptığını belirlemek için kod aracılığıyla uğraşmaktan yarım gün sonra tasarruf sağlar.

// Dear me in the future. Please, resolve this problem.

veya

// You think this code was written by somebody else. 
// No, it wasn't. You ([some name]) did it.

Kod yorumları kesinlikle bir "kod kokusu" değildir. Bu inanç tipik olarak, yorumların eski (eski) olabileceği ve sürdürülmesi zor olabileceği gerçeğinden gelir. Ancak, kodun neden belirli bir şekilde bir şey yaptığını açıklayan iyi yorumlara sahip olmak bakım için önemli olabilir (ve genellikle önemlidir).

İyi yorumlar, kodun ne yaptığını anlamayı kolaylaştırır ve daha da önemlisi neden belirli bir şekilde yaptığını belirler. Yorumlar programcılar tarafından okunmalı ve açık ve net olmalıdır. Anlaşılması zor veya yanlış olan bir yorum, hiç yorum yapmamaktan daha iyi değildir.

Kodunuza net ve kesin yorumlar eklemek, bir kod bölümünün "neyi" ve "nedenini" anlamak için belleğe güvenmeniz gerekmediği anlamına gelir. Bu, daha sonra bu koda baktığınızda veya başkasının kodunuza bakması gerektiğinde önemlidir. Yorumlar, kodunuzun metin içeriğinin bir parçası haline geldiğinden, açıkça yazılmasının yanı sıra iyi yazma ilkelerini izlemelidir.

İyi bir yorum yazmak için, kodun amacını (neden, nasıl değil) belgelemek ve kodun arkasındaki mantık ve mantığı olabildiğince açık bir şekilde belirtmek için elinizden geleni yapmalısınız. İdeal olarak, yorumlar kodu yazdığınız sırada yazılmalıdır. Beklerseniz, muhtemelen geri dönüp ekleyemezsiniz.

Sams 24 Saat İçinde Kendine Görsel C # 2010'u Öğretti, s. 348-349.

Kod, bir kütüphanede (problemi üçüncü taraf bir kütüphanede veya derleyici ile birlikte gelen bir kütüphanede) mevcut bir problemden kaçınmak için belirli bir şekilde yazılmışsa, yorum yapmak mantıklı olacaktır.
Ayrıca gelecekteki sürümlerde veya bir kitaplığın yeni bir sürümünü kullanırken veya örneğin PHP4'ten PHP5'e geçerken değiştirilmesi gereken kodu yorumlamakta fayda vardır.

En iyi yazılmış kitabın bile, muhtemelen bir giriş ve bölüm başlıkları vardır. İyi belgelenmiş koddaki yorumlar, üst düzey kavramları tanımlamak ve kodun nasıl düzenlendiğini açıklamak için yine de kullanışlıdır.

Onurlu söz, anti-kalıptır:

Bazen FLOSS lisans vaizlerinin dosya dokümantasyonu yerine sıklıkla kullanıldığı izlenimini edindim . GPL / BSDL hoş bir metin dolduruyor ve bundan sonra başka bir yorum bloğunu nadiren görüyorsunuz.

Kodu açıklamak için yorum yazmanın kötü olduğu fikrine katılmıyorum. Bu tamamen kodun hataları olduğunu görmezden gelir. Kod açık ne olabilir yapar yorumsuz. Bu kod ne açık olması olasılığı düşüktür sözde yapmak. Yorumlar olmadan sonuçların yanlış olduğunu veya yanlış kullanıldığını nasıl bildiniz?

Yorumlar , kodun amacını açıklamalıdır , böylece bir hata olursa, yorumları + kodu okuyan biri onu bulma şansına sahip olur.

Kodları yazmadan önce genellikle kendimi satır içi yorumlar yazarken buluyorum . Bu yolla, ne yapmaya çalıştığımı netleştiriyorum ve ne yapmaya çalıştığınızı gerçekten bilmeden bir algoritmada kaybolmayı azaltır.

Birisi, bir yöntemde 700 satır olmasının bir koku olduğunu düşünmesinin doğru olduğunu söyleyen yorumlar.

Yorumlarda bulunmazsanız, birileri aynı hatayı yapacaktır, çünkü yine de bir kokuyorsun.

Bazı kod analiz araçlarının talep ettiği için ayrıca yorumlar da kokuyor.

Olmaz İnsanlar hiç bir açıklama koymak veya diğer geliştiriciler için bile küçük bir yardım yazma da bir koku vardır. Kaç kişinin bir şeyler yazmadığına şaşırdım, ama sonra geri dönecek ve 3 ay önce ne yaptıklarını hatırlayamadıklarını kabul edecekler. Doküman yazmaktan hoşlanmıyorum, fakat insanlara aynı şeyleri tekrar tekrar söylemek zorunda kalmak istiyorum.

Kendime ait bir soru ile cevaplayacağım. Hatayı aşağıdaki kodsuz kodda bulabilir misin?

tl; dr: Kodunuzu koruyacak bir sonraki kişi sizin kadar tanrı gibi olmayabilir.

 [org 0x7c00]

 main:
  mov ah, 0x0e
  mov bx, string
  call strreverse
  call print

 stop:
  jmp $

 strreverse:
  pusha
  mov dx, bx
  mov cx, 0

 strreverse_push:
  mov al, [bx]
  cmp al, 0
  je strreverse_pop
  push ax
  add bx, 1
  add cx, 1
  jmp strreverse_push

 strreverse_pop:
  mov bx, dx

 strreverse_pop_loop:
  cmp cx, 0
  je strreverse_end
  pop ax
  mov [bx], al
  sub cx, 1
  add bx, 1
  jmp strreverse_pop_loop

 strreverse_end:
  popa
  ret

 print:
  pusha

 print_loop:
  mov al, [bx]
  cmp al, 1
  je print_end
  int 0x10
  add bx, 1
  jmp print_loop

 print_end:
  popa
  ret
 string:
  db 'Boot up', 0

 times 510 -( $ - $$ ) db 0
 dw 0xaa55

Kod ve yorumlar arasında bir denge sağlamalısınız ... Genellikle bir kod bloğuna devam eden bazı yorumlar eklemeye çalışırım. Çünkü kodu anlayamayacağım (aynı zamanda), ama kendi kodumu daha hızlı okuyabildiğim ve önemli olayların gerçekleştiği belirli bölümleri bulabildiğim için değil.

Her neyse, kendi kişisel kriterlerim "şüphede olduğunda yorum" dur. Anlayamayacağım, tamamen şifreli bir çizgiden çok fazladan bir çizgiye sahip olmayı tercih ederim. Bir süre sonra kod incelemesindeki yorumları her zaman kaldırabilirim (ve genellikle yaparım)

Ayrıca, yorumlar "Dikkatli olun! Girişin formatı ASCII değilse, bu kodun değişmesi gerekecek!"

Bunu okuduğumda, ilk kez okuduğum bir şey hatırladım (uzun bir listeden, fotokopiler alarak korunmuş)

Gerçek programcılar yorum yazmaz - eğer yazmak zorsa okumak zor olmalı

Oldukça eski bir koku düşüyor.

Kod yorumlamanın hayata çok zayıf bir başladığını düşünüyorum. Bugünlerde bilmiyorum ama ilk önce okulda programlama öğretilirken, "Sayıları 1-10'u ayrı satırlara yazdıran bir program yaz. Kodunuzu yorumladığınızdan emin olun." Yorum eklemediyseniz işaretlenirsiniz, çünkü kodunuzu yorumlamak iyi bir şeydir.

Ama böyle önemsiz bir süreç hakkında söylenecek ne var? Yani sen klasik bir yazı yazıyorsun.

i++; // add one to the "i" counter.

sadece iyi bir not almak için ve eğer bir aklınız varsa, anında kod yorumlarının çok düşük bir görüşünü oluşturur.

Kod yorumlama İYİ BİR ŞEY değildir. Bu, bazı şeyler için gerekli olan bir şey ve en üstteki cevabında Thomas Owens, gerekli olduğu durumlarla ilgili mükemmel bir açıklama sunuyor. Ancak, bu durumlar nadiren ev ödevi tipi görevlerde ortaya çıkar.

Birçok yönden, bir yorum eklemek son çare olarak düşünülmelidir, söylenmesi gerekenler programlama dilinin aktif kısımlarında açıkça söylenemediğinde. Her ne kadar nesne isimlendirme bayatlayabilse de, çeşitli insan ve bilgisayar geri bildirim eksikliği mekanizmaları yorumların korunmasını unutmayı kolaylaştırır ve sonuç olarak yorumlar aktif koddan çok daha hızlı bayatır. Bu nedenle, bir seçimin mümkün olduğu durumlarda, kodu daha açık hale getirmek için kodun değiştirilmesi, belirsiz kodların yorumlarda açıklanmasında her zaman tercih edilmelidir.

Tabii ki yorumlar bir kod kokusudur ...

Her programcı, hepimizin sonunda işlediğimiz , hata ayıkladığımız veya karşılaştığımız sade delilik nedeniyle çıldırdığını biliyor .

"Bunu yap!" proje yöneticiniz diyor.

"Bu yapılamaz" cevabını veriyorsun.

"O zaman yapacak başka birini bulacağız" diyorlar.

"Tamam, belki de yapılabilir" diyorsunuz.

Ve sonraki X günlerini, haftaları ... ayları… anlamaya çalışarak geçir. Süreç boyunca, denemeyi başaramazsınız, dener ve başarısız olursunuz. Bunu hepimiz yapıyoruz. Asıl cevap, iki tür programcı var, yorum yapanlar ve olmayanlar.

1) Gelecekte başvurmak üzere belgelemek, işe yaramayan başarısız rutinleri yorumlamak (işe yarayanı bulduktan sonra onları silmek değildir.) Ya da kodu yorumlarla bölmekle yapanlar ya kendi işlerini kolaylaştırıyorlar. biçimlendirme umarım biraz okumayı veya anlamayı kolaylaştırır. Cidden, onları suçlayamam. Ama sonunda, onlar kopar ve sonra bu var: // dammit this code sucks! swear! curse! i hate it! i am going to write something here to vent my anger!!!!

2) Süper kahraman gibi davranmayan ya da bir mağarada yaşayanlar . Onlar sadece başkaları ve kendileri için umursamaz bir şekilde umursamazlar ve kod ile daha az ilgilenebilirlerdi ya da daha sonra ne anlama gelebileceği konusunda.

Şimdi beni yanlış anlamayın .. Kendini belgeleyen değişkenler ve fonksiyonlar bunu tamamen önleyebilir .. ve güven bana asla yeterince kod temizleme yapamazsınız. Ancak basit gerçek şu ki, yedek tutmaya devam ettiğiniz sürece, HER ZAMAN yorumları silebilirsiniz.

Kodunuzda bazı yorumları kullanmamanın bir kod kokusu olduğunu iddia ediyorum . Kodun mümkün olduğu kadar kendiliğinden belgelenmesi gerektiği konusunda hemfikir olmama rağmen, kodun ne kadar iyi yazıldığına bakılmaksızın hiçbir anlam ifade etmeyen kodu göreceğiniz belirli bir noktaya çarpıyorsunuz. Yorumların hemen hemen zorunlu olduğu iş uygulamalarında bazı kodlar gördüm, çünkü:

1. Durum bazında bir şey yapmalısınız ve bunun için iyi bir mantık yok.
2. Yasalar değiştiğinde kodun bir veya iki yılda değişmesi ve onu hızlı bir şekilde tekrar bulmak istediğinizde.
3. Biri geçmişte kodu düzenledi çünkü kodun ne yaptığını anlamadı.

Ayrıca, şirket tarzı kılavuzları size belirli bir şeyi yapmanıza yardımcı olabilir - bir işlevde hangi kod bloklarının yapıldığını belirten yorumlarınızın olması gerektiğini söylerlerse, yorumları da ekleyin.

Yorumlar ve kod arasında büyük bir temel fark vardır: yorumlar, insanların fikirlerini başkalarına iletebilmelerinin bir yoludur, oysa kod öncelikle bilgisayar içindir. “Kod” da sadece isimler ve girintiler gibi insanlar için de birçok husus var. Ancak yorumlar kesinlikle insanlar için, insanlar tarafından yazılmıştır.

Bu nedenle, yorum yazmak her yazılı insan iletişiminde olduğu kadar zordur! Yazar, izleyicinin kim olduğu ve ne tür bir metne ihtiyaç duyacağı konusunda net bir anlayışa sahip olmalıdır. Yorumlarınızı on, yirmi yılda kimin okuyacağını nasıl bilebilirsin? Ya kişi tamamen farklı bir kültürden ise? Vb umarım herkes bunu anlar.

İçinde yaşadığım küçük homojen kültürün içinde bile fikirleri başkalarına iletmek çok zor. İnsan iletişimi genellikle kaza haricinde başarısız olur.

İş arkadaşınla aynı fikirdeyim. Hep kodumu yorum yaparsanız ben endişeliyim anlamına geldiğini söylemek ı anlamaya mümkün olmayacaktır kendi kodunu gelecekte. Bu kötü bir işaret.

Yorumların kodun içine dağılmasının tek nedeni, mantıklı görünmeyen bir şey söylemek.

Bu yorumlar genellikle şöyle bir şey şeklinde olur:

//xxx what the heck is this doing??

veya

// removed in version 2.0, but back for 2.1, now I'm taking out again

Varsa, fonksiyon argümanları ve geri dönüş birimleri, yapı alanları, hatta yerel değişkenler veren kod yorumları çok kullanışlı olabilir. Mars Orbiterini hatırla!

İşte benim kurallarım:

• Kodu yazın ve kodun kısa bir özetini ayrı bir belgede saklayın.
• Başka bir şey üzerinde çalışmak için kodu birkaç gün yalnız bırakın.
• Koda dön. Ne yapması gerektiğini hemen anlayamıyorsanız, özeti kaynak dosyaya ekleyin.

İş arkadaşınızı Okuryazar Programlama tekniği hakkında eğitin .

Hayır, yorumlar bir kod kokusu değil, sadece kötüye kullanılabilecek bir araçtır.

İyi yorum örnekleri :

// Bunun cm cinsinden olduğunu düşünüyorum. Daha fazla araştırma gerekli!

// X yapmanın akıllıca bir yolu

// Listenin burada boş olmadığı garanti edildi