it-swarm.dev

"Yorum bir kod kokusu"

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

100
Fishtoaster

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

Bir yöntemde veya blokta neler olduğunu bilmek istersem, kodu okurdum. Her neyse, belirli bir projede çalışan herhangi bir geliştiricinin en azından geliştirme dilini, yazılanları okuyacak ve ne yaptığını anlayacak kadar tanıdıklarını umuyorum.

Bazı aşırı optimizasyon durumlarında, birisinin kodunuzun ne yaptığını takip etmesini zorlaştıran teknikler kullanıyor olabilirsiniz. Bu durumlarda, yorumlar yalnızca bu tür optimizasyonlara neden sahip olduğunuzu değil, kodun ne yaptığını açıklamak için kullanılabilir ve kullanılmalıdır. İyi bir kural, uygulama diline ve projeye aşina olan bir başkasının (veya birden fazla kişinin) kodunuza bakmasıdır - hem nedenini hem de nasıl olduğunu anlayamazlarsa, hem neden hem de nasıl.

Ancak, kodda net olmayan şey, neden bir şey yaptığınızdır. Başkaları için açık olmayan bir yaklaşım benimserseniz, verdiğiniz kararları neden verdiğinizi açıklayan bir yorumunuz olmalıdır. İnsanların neden Y yerine X yaptığınızı bilmek istedikleri bir kod incelemesi gibi bir şeye kadar bir yorumun gerekli olduğunu fark etmeyeceğinizden şüphelenebilirim - cevabınızı ona bakan herkes için kodda yakalayabilirsiniz gelecekte.

Ancak en önemli şey, kodunuzu değiştirdiğinizde yorumlarınızı değiştirmektir. Bir algoritmayı değiştirirseniz, yorumları Y üzerinde X algoritmasıyla neden gittiğinizle güncellediğinizden emin olun. Eski yorumlar çok daha büyük bir kod kokusudur.

167
Thomas Owens

Bu şu anda duymak özellikle rahatsız edici, bu hafta sonu bir araştırma algoritması (aslında yayınlanmamış bir) uygulayan çok iyi adlandırılmış, çok temiz, uncommented kod bakarak biraz zaman geçirdim. Ben üst düzey aşina, yanımda oturan adam mucit ve kod birkaç yıl önce başka biri tarafından yazılmıştır. Takip edebiliriz ancak.

İş arkadaşınız yeterince deneyimli değil.

110
Paul Nathan

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

How tipi yorumlar genellikle yeniden düzenleme ile daha iyi ele alınır. Şahsen, genellikle yeniden düzenleme lehine yorumlardan 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)
75
Sam Saffron

İş arkadaşınıza bir sapkın ilan ediyorum! Heretik yakıcı botlarım nerede?

Obsesif yorumlama kötü ve bakım başağrısıdır ve yorumlar iyi bilinen yöntemlerin, sınıfların, değişkenlerin vb. Yerine geçmez. neden bir şey, altı ay içinde kodu korumak zorunda olan zavallı aptal için son derece değerli olabilir - özellikle de bu zavallı aptal siz olduğunuzda.

Ü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.

32
BlairHippo

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

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

i++; // Increment i by 1

Daha sonra, iyi (ve sürdürülen/hizalanan) bir kod tasarımı ve dokümantasyonu varsa, yorum yapmak daha az yararlıdır.

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

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

Ayrıca yorumları korumak ve senkronize tutmak zorunda unutmayın ... eski veya yanlış yorumlar korkunç bir acı olabilir! Ve genel bir kural olarak, çok fazla yorum yapmak kötü programlamanın bir belirtisi olabilir.

29
Wizard79

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

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

Diğer yanıtların çoğu, yorumların ne zaman garanti edileceği konusunda iyi tavsiyeler verir.

Şahsen çok az yorum kullanıyorum. Açık olmayan süreçlerin amacını açıklayın ve ara sıra ölüm tehdidini haftalarca ayarlanması gereken şeyleri kendi başlarına değiştirmeyi düşünebilecek herkese bırakın.

Bir anaokulu sahibi anlayabilene kadar her şeyi yeniden düzenlemek, muhtemelen zamanınızın verimli bir kullanımı değildir ve muhtemelen daha kısa bir versiyon kadar iyi performans göstermeyecektir.

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

26
Bill

Burada asıl mesele "kod kokusu" teriminin anlamıdır.

Birçok kişi (siz de dahil, bence) bir kod kokusunun bir hataya yakın bir şey olduğunu veya en azından düzeltilmesi gereken bir şey olduğunu anlar. Belki de bunu "anti-pattern" ile eşanlamlı olarak düşünüyorsunuz.

Bu terimin anlamı değil!

Kod kokusu metaforu Wards Wiki kaynağından kaynaklanır ve vurgulamaktadır:

Bir CodeSmell bir şeyin yanlış olabileceğine dair bir ipucu olduğuna dikkat edin. Mükemmel derecede iyi bir deyim bir CodeSmell olarak düşünülebilir, çünkü genellikle yanlış kullanılır veya çoğu durumda çalışan daha basit bir alternatif vardır. Bir şeyi CodeSmell olarak adlandırmak bir saldırı değildir; daha yakından bakmanın bir işareti.

Peki, yorumların bir kod kokusu olduğu ne anlama geliyor: Bir yorum gördüğünüzde duraklatmalı ve düşünmelisiniz: "Hmmm, bir şeyin iyileştirilebileceğine dair bir ipucu hissediyorum". Belki bir değişkeni yeniden adlandırabilir, "özütleme yöntemi" -refactoring - veya belki de yorum aslında en iyi çözümdür.

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

EDIT: Ben sadece benden daha iyi açıklayan bu iki makale üzerinde durdum:

23
Rasmus Faber

Bazı durumlarda, hiçbir yorum iyi adlandırma, yeniden düzenleme vb. İfadelerin yerini tutamaz. Sadece bu gerçek dünya örneğine bakın (dil harika):

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

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

Şimdi aynı yorumlar:

  // 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
23
user281377

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

21

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 kurtulmak için yöntemleri kolayca çıkarmanızı sağlar,
sadece kodun bunları söylemesine izin ver! Bunun nasıl güzel bir şekilde yeniden yazıldığını (kes/yapıştır) 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ılamayan şeyler için yöntemleri çıkarmayın ve yorumların altına kodu yazın.

Bu, minimum düzeyde yorum yapmaya devam etmenin yararlı bir yolu olarak gördüğüm şeydir, her satırı yorumlamak gerçekten işe yaramaz ... Yalnızca tek bir satırı, sihirli bir değer başlatma ile veya anlamlı olduğu yerde belgelendirin.

Parametreler çok fazla kullanılırsa, bunlar sınıfınızda özel üyeler olmalıdır.

11
Tamara Wijsman

Bence cevap her zamanki “duruma bağlıdır”. Kodu sadece yorum koduna yorumlamak bir koku. Kodun yorumlanması, çünkü büyüklük sırası daha hızlı olan belirsiz bir algoritma kullandığınızdan, bakım programlayıcısını (genellikle yazdıktan sonra 6 ay sonra) kaydeder, ne yaptığını belirlemek için kodun üzerinden yarım gün geçirir.

10
Brandon
// 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.
10
Zzz

Kod yorumları kesinlikle bir "kod kokusu" değildir. Bu inanç tipik olarak yorumların eski (güncelliğini yitirmiş) olabileceği ve sürdürülmesinin zor olabileceği gerçeğinden kaynaklanmaktadır. Bununla birlikte, 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ı ve daha da önemlisi, bunu neden belirli bir şekilde yaptığını anlamayı kolaylaştırır. Yorumlar programcılar tarafından okunmalıdır ve açık ve net olmalıdır. Anlaması zor veya yanlış bir yorum, hiç yorum yapmaktan daha iyi değildir.

Kodunuza net ve kesin yorumlar eklemek, bir kod bölümünün “ne” ve “nedenini” anlamak için belleğe güvenmeniz gerekmediği anlamına gelir. Bu, daha sonra bu koda baktığınızda veya başka birinin kodunuza bakması gerektiğinde önemlidir. Yorumlar kodunuzun metinsel içeriğinin bir parçası olduğu için, açık bir şekilde yazılmanın yanı sıra iyi yazma ilkelerine de uymalıdırlar.

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

Sams 24 Saatte Görsel C # 2010'u Öğretin , s.348-349.

8
Scott Dorman

Kod, bir kitaplıkta (hem üçüncü taraf kitaplığı hem de derleyiciyle birlikte gelen kitaplık) var olan bir sorunu önlemek için belirli bir şekilde yazıldıysa, yorum yapmak mantıklıdır.
Ayrıca, gelecekteki sürümlerde veya kitaplığın yeni bir sürümünü kullanırken veya örneğin PHP4'ten PHP5'e geçerken değiştirilmesi gereken kodu yorumlamak da anlamlıdır.

6
kiamlaluno

En iyi yazılmış kitap bile muhtemelen bir giriş ve bölüm başlıklarına sahiptir. İyi belgelenmiş koddaki yorumlar, üst düzey kavramları tanımlamak ve kodun nasıl düzenlendiğini açıklamak için hala yararlıdır.

6
munificent

Şerefli söz, anti-kalıptır:

FLOSS lisans ön eklerinin bazen dosya belgelerinin yerine kullanıldığına dair izlenimim var. GPL/BSDL Güzel bir dolgu metni yapar ve bundan sonra nadiren başka bir yorum bloğu görürsünüz.

4
mario

Kodu açıklamak için yorum yazmanın kötü olduğu fikrine katılmıyorum. Bu, kodun hatalara sahip olduğu gerçeğini tamamen yok sayar. Kodun yorum yapmadan yaptığı ne olduğu açık olabilir. Kodun ne olduğunu netleştirmek daha az olasıdır varsayalım. Yorum yapmadan, sonuçların yanlış olup olmadığını veya yanlış kullanıldığını nasıl anlarsınız?

Yorumlar, kodun niyet değerini açıklamalıdır, böylece bir hata varsa, yorumları + kodunu okuyan birisinin kodu bulma şansı vardır.

Genelde satır içi yorum yazarken kendimi bulurum önce Kod yazıyorum. Bu şekilde, kod yazmak için ne yapmaya çalıştığım açıktır ve gerçekten ne yapmaya çalıştığınızı bilmeden bir algoritmada kaybolmayı azaltır.

4
Danny Tuppeny

Kendi sorumla cevaplayacağım. Hatayı aşağıdaki önerilmeyen kodda bulabilir misiniz?

tl; dr: Kodunuzu koruyacak bir sonraki kişi sizin kadar tanrısal 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
3
Ant

Birisi bir yöntemde 700 satırın bir koku olduğunu düşünüyor çünkü koymak yorumlar.

Yorumlar var çünkü bir yorumda bulunmazsanız, birileri aynı hatayı yapacaktır, yine bir koku.

Bazı kod analiz aracı da bir koku olmasını talep ettiği için yorumlar yazılmıştır.

Hiç yorum yapmazlar, ya da diğer geliştiriciler için biraz yardım bile yazmazlar da bir koku. Kaç kişinin bir şeyler yazamayacağına şaşırdım, ama sonra dönüp 3 ay önce yaptıklarını hatırlayamadıklarını kabul edeceğim. Doküman yazmaktan hoşlanmıyorum, ama insanlara aynı şeyi tekrar tekrar anlatmaktan hoşlanıyorum.

3
MIA

Kod ve yorumlar arasında bir denge kurmalısınız ... Genellikle bir kod bloğuna devam eden bazı yorumlar eklemeye çalışırım. Kodu anlayamayacağım için değil (iyi, aynı zamanda), ancak kendi kodumu daha hızlı okuyabildiğim ve önemli bölümlerin olduğu belirli bölümleri bulabildiğim için değil.

Her neyse, kendi kişisel kriterlerim "şüpheye düştüğünüzde, yorum". Anlayamayacağım tamamen şifreli bir çizgiden daha fazla bir çizgiye sahip olmayı tercih ederim. Bir süre sonra kod incelemesindeki yorumları her zaman kaldırabilirim (ve genellikle yaparım)

Ayrıca, "dikkatli olun! Girişin biçimi ASCII değilse, bu kodun değişmesi gerekir!"

2
Khelben

Kod yorumlamanın hayata çok kötü başladığını düşünüyorum. Bu günleri bilmiyorum, ama okulda ilk programlamayı öğrettiğimde, "Sayıları bir ila on arasında ayrı satırlara yazdıran bir program yaz. Kodunuzu yorumladığınızdan emin olun." Kodunuzu yorumlamak İYİ BİR ŞEY olduğu için yorum eklemediyseniz işaretlenirsiniz.

Fakat bu kadar önemsiz bir süreç hakkında söylenecek ne var? Böylece klasiği yazıyorsunuz

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

sadece iyi bir not almak ve herhangi bir nous varsa, anında kod yorumlarının çok düşük bir görüşünü oluşturmak.

Kod yorumlama İYİ BİR ŞEY değildir. Bu bir nevi GEREKLİ ŞEYTİR ve en üstteki yanıtta Thomas Owens, gerekli olduğu durumların mükemmel bir açıklamasını sağlar. Bununla birlikte, bu durumlar ödev tipi ödevlerde nadiren ortaya çıkar.

Pek çok açıdan, bir yorum eklemek son çare seçimi olarak düşünülmelidir, söylenmesi gereken şey programlama dilinin aktif kısımlarında açıkça söylenemediğinde. Nesne adlandırma 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ı batar. Bu nedenle, bir seçeneğin mümkün olduğu durumlarda, anlaşılır kılmak için kodu değiştirmek her zaman açık kodun yorumlarla açıklanmasına tercih edilmelidir.

2
Alohci

Bunu okurken, onlarca yıl önce (daha uzun listeden, fotokopi çekerek korunan) okuduğum bir şey hatırlatılır:

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

Oldukça eski bir koku methinks.

2
Murph

Tabii ki yorumlar bir kod kokusu ...

her programcı, işin miktarı, hata ayıklama veya karşılaştığımız düz delilik nedeniyle hepimizin sonunda delirdiğini bilir.

"Bunu yap!" proje yöneticiniz diyor.

"Bu yapılamaz."

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

"Tamam, belki de yapılabilir" diyorsunuz.

Ve sonraki X sayısını günler ... haftalar .. aylar .. anlamaya çalışın. Süreç boyunca, denemek ve başarısız olacak ve denemek ve başarısız. Hepimiz bunu yapıyoruz. Gerçek cevap, yorum yapan ve yapmayan iki tür programcı olmasıdır.

1) Yapanlar, ileride başvurmak üzere belgeleyerek, işe yaramayan başarısız rutinleri yorumlayarak (işe yarayanı bulduktan sonra koku onları silmez.) Veya kodu yorumla parçalayarak kendi işlerini kolaylaştırırlar. umarım biçimlendirmesi okumayı veya anlamayı biraz daha kolaylaştırır. Cidden, onları suçlayamam. Ama sonunda, çırpınıyorlar ve sonra buna sahipsiniz: // dammit this code sucks! swear! curse! i hate it! i am going to write something here to vent my anger!!!!

2) Ya bir süper kahraman gibi davranmayan ya da bir mağarada yaşıyorlar. Başkaları, kendileri için pervasız bir şekilde göz ardı ediyorlar ve kod veya daha sonra ne anlama gelebileceği konusunda daha az umursabilirler.

Şimdi beni yanlış anlamayın .. değişkenleri ve fonksiyonları kendi kendine belgelemek bunu tamamen önleyebilir .. ve güven bana asla yeterli kod temizleme yapamazsınız. Ancak basit gerçek şu ki, yedekleri sakladığınız sürece [~ # ~] her zaman [~ # ~] yorumları silebilirsiniz.

1
Talvi Watia

Yorumlar ve kod arasında büyük bir temel fark vardır: yorumlar insanların fikirleri diğer insanlara iletmesinin bir yoludur, oysa kod öncelikle bilgisayar içindir. "Kod" da, adlandırma ve girintileme gibi yalnızca insanlar için birçok yön vardır. Ancak yorumlar kesinlikle insanlar için, insanlar tarafından yazılır.

Bu nedenle, yorum yazmak yazılı insan iletişimi kadar zor! Yazarın dinleyicinin kim olduğu ve ne tür bir metne ihtiyacı olacağı konusunda net bir anlayışı olmalıdır. On, yirmi yılda yorumlarınızı kimin okuyacağını nasıl bilebilirsiniz? Ya kişi tamamen farklı bir kültürden geliyorsa? Vb. Umarım herkes bunu anlar.

İçinde yaşadığım küçük homojen kültürün içinde bile, fikirleri diğer insanlara iletmek çok zor. İnsan iletişimi kaza dışında genellikle başarısız olur.

1
user15127

Kodunuzda bazı açıklamaları kullanmamanın bir kod kokusu olduğunu iddia ediyorum. Kodun olabildiğince kendi kendini belgelemesi gerektiğini kabul etsem de, kodun ne kadar iyi yazıldığına bakılmaksızın mantıklı olmayan 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 şeyler yapmanız gerekir ve bunun için iyi bir mantık yoktur.
  2. Yasalar değiştirildiğinde ve kodu tekrar hızlı bir şekilde bulmak istediğinizde, kod muhtemelen bir veya iki yıl içinde değişecektir.
  3. Birisi geçmişte kodu düzenledi çünkü kodun ne yaptığını anlamadılar.

Ayrıca, şirket stil kılavuzları belirli bir şekilde bir şey yapmanızı söyleyebilir - eğer bir fonksiyondaki kod bloklarının ne yaptığını belirten yorumlarınız olabileceğini söylüyorlarsa, yorumları ekleyin.

1
rjzii

İş arkadaşınızla aynı fikirdeyim. Ben her zaman kodumu yorum, bu [~ # ~] i [~ # ~] anlamaya mümkün olmayacağını söylüyor kendi kodum gelecekte. Bu kötü bir işaret.

Yorumları kodun içine serpiştirmemin diğer tek nedeni, mantıklı gelmeyen bir şey çağırmaktır.

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
0
Ken

İşte benim kuralı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.
0
Maxpm

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

0
SK-logic

Kod yorumları, uygulanabilir olduğunda, fonksiyon argümanları ve getirileri birimleri, yapı alanları, hatta yerel değişkenler bile çok kullanışlı olabilir. Mars Orbiter'ini hatırla!

0
dmuir

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

iyi yorum örnekleri:

// Sanırım bu cm cinsindendir. Daha fazla araştırmaya ihtiyaç var!

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

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

0
Andres F.

Ancak hiç anlaşılamayan kod çok daha büyük kod kokusu…

Lütfen üzerinde çalışmam için temiz kod ver
bu bir seçenek değilse, yorumlarla birlikte “kirli” kod almayı tercih ederim
yorumsuz kirli koddan daha.

0
Ian

Kelimelerin çoğu ağzımdan çıkarıldı. Ama her şeyi özetlemeliyim: yorumların noktası, kodun ne yaptığının üst düzey bir açıklamasını/açıklamasını vermektir.

Dahası, yorumları nasıl kullandığımın birkaç örneği:

  • başlık olarak, bir kod bölümünün genel amacını belirtmek için
  • kodu nereden aldığımı not etmek ve böylece intihalden kaçınmak
  • zaman zaman blokların sonunda, hangi blokun sonu olduğunu hatırlatmak için
  • şüpheli görünebilecek kodun amaçlandığını belirtmek (örneğin, bir anahtar durumu düştüğünde tuhaf zamanlar)
  • algoritmanın arkasındaki matematiği açıklamak
0
Stewart

Kimse bu konuda şimdiye kadar bu konu dedi, ben yapacağım:

Tür adları, değişken adları, işlev adları, yöntem adları ve yorumlar yalnızca kodunuzla ilgili meta verilerdir ve derleyicinin oluşturduğu makine koduyla hiçbir ilgisi yoktur (dışa aktarılan ve hata ayıklama sembollerinin adları hariç).

Tür adları ve değişken adları isimleriniz, işlev ve yöntem adları fiillerinizdir, bunlarla yapılacak adımları açıklarsınız. Yorumlar her şey içindir.

Bazı örnekler:

double temperature; // In Kelvins.


/**
 * Returns true if ray hits the triangle
 */
bool castRayOnTriangle(Triangle t, Ray r)
{
    //...
    if (determinant == 0)
    {
        /* The ray and the triangle are parallel, no intersection possible.*/
        return false;
    }
    //...
}


/* X algorithm. Visit http://en.wikipedia.org/... for details.*/
<implementation of something difficult to understand for the layman algorithm. >

Yorumlar güncellenmezlerse eskimiş olabilir, ancak değişken ve işlev adları da eskimiş olabilir. Geçenlerde bir C yapısında tamponlar veya işaretçilerle ilgisi olmayan bir bufPtr alanı ile karşılaştım. Ve sönük bir veri değil tam bir GZIP dosyası açmak için bir inflateBuffer işlevi gördüm ... Bunlar eski yorumlar kadar can sıkıcı.

0
Calmarius

Çok fazla cevap takım olarak programlamayı düşünüyor gibi görünmüyor. Ben kıdemli bir geliştiriciyim ve anlamamın basit bir yolunu açıklamaya yönelik yorumlar yazma eğilimindeyim.

Bunu ölümünden sonra bir takım iletişim veya eğitim olarak görüyorum. Ekibi kullandıkları koda bakmaya teşvik ediyorum, ama belki daha iyi anlamak için yazmadım.

Bu haftadan birkaç örnek (PHP kodu):

//Pattern for finding jpeg photos
//Case insensitive pattern for jpg and jpeg
const PATTERN_PHOTO = "*.{[jJ][pP][gG],[jJ][pP][eE][gG]}";

Umarım PATTERN_PHOTO daha sonra ne yaptığını açıklamak için kod yararlı olacaktır, ama yorum olmadan bu özel desen ne bir genç geliştirici için ne kadar açık olurdu?

Aynı kod kümesi:

//Ignore . and .. directories in Linux
if($file != "." && $file != "..")

Geliştiricilerimizin PHP'yi bildiği yönünde bir beklenti var, ancak barındırma için kullandığımız Linux işletim sistemini anladıklarından değil.

Dolayısıyla, bu yorumları, ekibimizin toplam verimliliğini artırmak için çok az zaman harcadığını düşünüyorum.

  • Nasıl çalıştığını anlamadıkları için kodu yeniden yazan daha az insan var. "Ne yapması gerektiğini nasıl anlamadım, bu yüzden çözdüm." Cidden, bununla daha önce uğraşmak zorunda kaldım.
  • Bireysel kod parçaları hakkında daha az soru sorulur. Soruları sadece bir kez cevaplamak, genellikle kodu ve kendimi yeniden tanımam için zamanı aramayı gerektirir. Ve bazen aynı soruyu haftalar boyunca birden fazla kişiden alırım. (Evet, yukarıdaki örnekler kadar basit şeylerde olurd)
  • Diğer geliştiriciler kendi başlarına öğrenmeye teşvik edilir ve yönlendirilir. Eğer karşılaşırlarsa //Ignore . and .. directories in Linux muhtemelen Google'a atlarlar ve aniden Linux'u biraz daha iyi anlarlardı.
0
Chris