Bir arama yaptım ama aradığımı bulamadım, eğer bu soru daha önce sorulsaydı, lütfen bağlantıya geçmekten çekinmeyin.

Bu ayın başlarında bu yazı yapıldı:

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/

Özetlemek gerekirse, yorum yazmazsanız, kötü bir programcısınız. Benim kişisel görüşüm, kodun tanımlayıcı olması gerektiği ve kodun kendi kendini tanımlayamadığı sürece çoğunlukla yorum gerektirmemesi gerektiğidir.

Verilen örnekte

// Get the extension off the image filename  
$pieces = explode('.', $image_name);  
$extension = array_pop($pieces);  

Yazar bu kodun bir yorum yapılması gerektiğini söyledi, benim kişisel görüşüm kodun açıklayıcı bir işlev çağrısı olması gerektiği:

$extension = GetFileExtension($image_filename);

Ancak yorumlarda birisi aslında sadece bu öneride bulundu:

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/comment-page-2/#comment-357130

Yazar, yorum yapan kişinin "bu insanlardan biri" olduğunu, yani kötü bir programcı olduğunu söyleyerek cevap verdi.

Herkes Kendi Kendini Tanımlı Kodla Yorum Yazan Kod hakkındaki görüşlerini nelerdir?

Kendini belgeleyen kod yazmayı tercih ederim. Bunun için bir rehber Temiz Koddur .

Elbette bu, hiç kimsenin yorumları kullanmaması gerektiği anlamına gelmez - rolleri vardır, ancak IMHO bunları dikkatle kullanmanız gerekir. SO hakkındaki bu daha önceki cevabım , konu hakkındaki düşüncelerimi daha ayrıntılı olarak açıklıyor.

Tabii ki, @Niphra'nın belirttiği gibi, temiz olduğuna inandığım şeyin başkaları tarafından gerçekten anlaşılabilir olduğunu kontrol etmek her zaman iki kat daha fazla değerdir. Ancak bu da bir uygulama meselesidir. Üniversiteye geri döndüğümde, hevesime göre, tüm kod varlıkları için garip ve komik isimler kullanmaktan dolayı şifreli kod parçaları yazdım. Öğretmenim ödevlerimden birini geri atana kadar kibarca hangi modülün ana olduğunu anlayamadığını belirterek :-) Bu iyi bir dersti, o zamandan beri daha okunaklı kod yazmaya odaklanmaya çalıştım. Bugünlerde takım arkadaşlarımdan neredeyse hiç şikayet almadım.

Kodun ne yaptığını belgelememelisiniz, ancak neden yaptığını belgelemelisiniz.

Hiçbir miktar adlandırma hilesi, neden ve nerede olduğunu göstermez, bu nedenle çeşitli kod bitlerinin amacını açıklamak için yorumlar eklemeniz gerekir.

Diğer tüm yorumlar güvenle kurtulabilirsiniz.

Aslında kendini tanımlayan koda inanmıyorum . Orada daha okunabilir kod ve daha az okunabilir kod (orijinal yazar olarak) bunu sizin bilgi, okumayı adam ve kod fonksiyonunun bilgi, dile bağlı. Ama hayır, yine de ... kısa bir yorum ile açıklanmalı.

Şimdi benim için açık olan şey, bu düşünce alanında olduğumda, tamamen farklı bir şey düşündüğümde ve kodun bu bölümünü tekrar kullanmam gerektiğinde, bir yıl içinde muhtemelen benim için net olmayacak.

Yani, kodunuzu yorumlayın. Elbette her satır (iyi gökler, hayır) değil, bir fonksiyon / alt program / modül ya da özellikle zorlu bir bölümün üstüne birkaç satır yorum yazıp kısaca ne yaptığını söyleyin. Bir veya iki yıl içinde kendinize teşekkür edeceksiniz.

Neyse ki, bu tartışmadaki her iki kamp da burada temsil edilmektedir ve her ikisi için de yanlısı ve aleyhte tartışmalardan bahsedilmiştir.

Her iki kampın da birbiriyle örtüşen argümanları olduğuna inanıyorum ve aslında pek çoğu üzerinde hemfikir olmaları konusunda aynı fikirdeler.

Örtüşen argümanlar

• Kod okunabilir olmalıdır.
• Yorumlar, koddakiyle aynı şeyi söylememeli, ancak gerektiğinde daha fazla bilgi vermelidir.
• Tüm değişken / fonksiyon isimlerine iyi düşünce verilmelidir, bu yüzden ne olduklarını / yaptıklarını iyi bir şekilde gösterirler.
• Yinelenen kod engellenmeli.

Şimdi, temel fark, bu argümanların bazılarına ne kadar ağırlık konulduğudır.

Kendi kendini tanımlayan kod

• Yorumlar kullanılmayabilir, bu nedenle bunları kullanmak en aza indirir, çünkü yanlış yorumlar hiçbir yorumdan daha kötü değildir.
• Yorumlar kodun bir kopyasıdır. Kodda yazılabilecek her şey kodda yazılmalıdır.

Daha fazla yorum

• Yorumlar koddan daha okunur. Düz İngilizce bir şey anlatmakta daha iyidir.

• Düz kod genellikle, nasıl olsa yorumlanması gereken belirsizliğe neden olur. Bunu kodda açıklamaya çalışmak, çok uzun adlarla sonuçlanır. Ayrıca, yalnızca ilk karşılaştığınızda ihtiyaç duyduğunuz 'ekstra' bilgilerle sürekli olarak karşılaşırsınız.

Her iki kampın da çok geçerli tartışmaları olduğuna inanıyorum, ancak bir konuyu çözdüğü için çılgınca bir kamp izlememelisiniz.

Göstermek için, Temiz Kod kitabında , kod yalnızca bir kez çağrılan çok sayıda daha küçük yöntemlere bölünür. Yöntemler tek nedeni kodlama (ve daha kolay TDD) belgelendirmek için oluşturulur. Bu, Hell Fonksiyonu ile sonuçlanır . Kod başlangıçta olduğundan daha az okunabilir ve yeniden yapılanma sırasında, yeniden kullanılabilir kodun içine alınabileceği düşünülmedi.

Öte yandan, 'yorumlar iyi olduğu için' her fonksiyonun yorumlandığı API’leri sık sık görüyorsunuz. Yorumlanması gereken şeyler hala değildir.

"Üzgünüm ama o herif."

Neden yorum yapmayı sevmediğini merak ediyorum: P

Cidden, kodlama, bir insanın gerçekten böyle kapsamlı bir açıklamada bulunabileceği bir sanattır. Bazen yorumlara, bazen daha çok ve daha iyi adlandırılmış fonksiyonlara ihtiyacınız vardır. Genellikle ikisi de.

Okuryazar programlamayı aşırı bir stil olarak görün.

Kısa, Daha İyi ve Doğru Cevap

İyi yazılmış, "kendi kendine belgelendirilmiş kod" düşüncesi tek ihtiyacınız olan bir anti-kalıptır ve "neden" i açıklayan yorumlar için istisnalar olsa bile ölmelidir . Herhangi bir programcının izleyebileceği ve alabileceği bir algoritma için her zaman tüm kodları yazabildiğiniz bir efsanedir (veya sahip olmadığınız yeniden düzenleme veya organizasyon zamanını gerektirmez). Daha da önemlisi, daha sık olmasa da, açık kod yazdıklarını düşünen programcılar bunu yapmazlar.

Yorumlardan çok daha iyi bir cevap sadece “neden” i açıklamak için kullanılmalıdır :

• "neden" i açıkla (elbette)
• Münferit satırlarda "ne" i açıklayın, ancak kod karmaşık olduğunda veya amaç belirsiz olduğunda ve daha da basitleştirmeye değmezse
• İhtiyacınız olanı anlama ve bulma konusunda kod blokları için "neyi" açıklayın

Yedeklemeye İlişkin Açıklama

İnsanlar yanlışlıkla insanların yorumları kullanmasının tek sebebinin bir kod satırının ne anlama geldiğini açıklamak olduğunu düşünmeleridir. Gerçek şu ki, yorum yapan kodun büyük bir amacı bunu yapmaktır. daha hızlıkodunuza göz atmak ve aradığınızı bulmak için. Daha sonra koda döndüğümde veya bir başkasının kodunu okuduğumda, elbette iyi yazılmış bir kodun bir bölümünü okuyabilir ve anlayabilirim; aradığım şey değilse, tamamen atlayın? İyi bir şekilde yazılsa bile, neden birkaç oturuma bakıp, bir fonksiyonun tamamını anlayabiliyorsanız, neden orada oturun ve kodu anlayın? Bu yüzden işlevler için tanımlayıcı adlar kullanıyoruz - kimse işlevim için tanımlayıcı bir isim kullanmaya ihtiyacım olmadığını söylemiyor, çünkü birisi ne yaptığını görmek için açıkça yazılmış koduma bakabiliyor.

Örneğin, başka birinin işlevine bakıyorsam, ne yaptığını görmek için kod boyunca satır satır gitmek ya da işlevin tam olarak ne yaptığını ve nerede olduğunu görmek için işlev boyunca üç iyi yazılmış yoruma göz atmak daha kolay mıdır? yapıyor mu?

Başka bir anti-patern, kodunuzu yorumlamak için işlevlerin aşırı kullanılmasıdır. İyi adlandırılmış işlevler, kod belgelerinin önemli bir parçasıdır, ancak bazen programcılar, hiçbir zaman başka hiçbir yerde belge işlevi için bir işlev olarak kullanılmayacak olan 2-3 kod satırı ayırır. Aşırı kullanım işlevleri neden aşırı açıklama yorumlarından daha iyidir? Bunun gibi işlevler kullanmak, GOTO ifadelerini kucaklamakla aynıdır - takip edilmesi acı verici bir spagetti kodu oluşturur.

Temel olarak, insanların sürekli olarak kodu paylaştığı ve insanların kodlarını mükemmelleştirmek için her zaman zamanlarının olmadığı bir işletme ortamında çalışırken, birkaç iyi yorum tonlarca zaman ve hayal kırıklığı kazandırabilir. Ve unutmayın, kodunuzu ışık hızında okuyabilen bir guru olabilirken, ofisinizdeki herkes değil.

Ayrıca size açık veya “kendi kendine belgeleyen” bir şeyi hatırlamanız gerekiyor, başkası için olmayabilir ... Belki de bazı işlevleri daha az anlayan biri. Bu yüzden hemen her şey hakkında yorum yapıyorum.

Kendini belgeleme koduna sahip olan şey, bu işlevin içinde bulacağınız şey:

$pieces = explode('.', $image_name);  
$extension = array_pop($pieces);  

Bu sadece iki satır olduğundan fonksiyon ismine sahip olduğunuzda kendini açıklar. İşler daha karmaşık hale geldiğinde, açıklayıcı bir ada sahip bir fonksiyondaki her birkaç kod satırını sarmanız ya da gerektiğinde yorumları kullanmanız gerekir .

Neden ve / veya yerine bir veya / veya madde olması gerektiğini anlamadım. Evet, kodunuzu olabildiğince kendi kendine belgelendirin ve evet, aksi takdirde net olmayan kısımlara bazı yorumlar ekleyin.

Yorumlar ve kendi kendini belgeleyen temiz kod farklıdır. Kod her şeyin nasıl yapılacağı ile ilgilidir. Ve yorumlar , diliniz ne olursa olsun , neden kodda açıklanamayan kısmı kapsamalıdır . Ayrıca, eğer diliniz çok sınırlıysa ve sözleşmeniz, statik özellikleriniz ve hatta iddialarınız yoksa, yorumlar kodunuzun sınır konularını kapsamalıdır.

Bu durumda, tanımlayıcı bir işlev yapmak kolaydır. Ancak, kodlarının kendi kendini belgeleme olduğuna inanan iyi programcılar tarafından yapılan birçok kodu okudum ve kendileri için net olan şeyler gerçekten kafa karıştırıcıydı.

$ extension = GetFileExtension ($ image_name);

Örneğinize geri dönmek için, bir dizi görüntü adı gönderebilir miyim, yoksa sadece bir görüntü mü alır? Herhangi bir dosya türünü veya yalnızca bazılarını destekliyor mu? Kordonu benim için emniyete alacak mı, yoksa yapmak zorunda mıyım? Dosya tipi yoksa, bana haber veriyor mu?

Tabii ki, bunu biraz geriyorum. Ancak, audio_band genişliğinin ve video_band genişliğinin kendi kendini belgeleyen isimler olduğuna inanan bir programcıyı hatırlıyorum; ortaya çıkan sesin bayt ve videonun kilobayt cinsinden ifade edilmesi gerekiyordu. Bunu anlamak için çok zaman aldı.

Biri diğerini dışlamaz. Kodunuz kendi kendini yorumlasa da, kendi yorumunuzu yapan kodun neden yaptığını açıklamak için düzenli olarak yorum yapmanız gerekebilir .

Bu yazıya katılmıyorum ve bir dereceye kadar sizinle aynı fikirdeyim. İyi yöntem adları, iyi değişken adları ve tek bir şey yapan küçük yöntemler kullanırsanız, kodun izlemesi kolay olmalıdır.

Zekice olmamaya çalışın çünkü zeki kod korkunç bir okuma ve bakımdır. Anahtar kelime: devam et !

Benim düşüncem, yorumların nedenini değil neyi açıklaması gerektiğidir. Bu varsayımsal mükemmel dünyada, kodunuzun kolay okumayı sağlayacak kadar temiz olduğunu, ne yaptığını açıklamanıza gerek olmadığını, ancak neden böyle ya da böyle yapmayı seçtiğinizi unutmayın.

Bir kaynak kontrol sistemi kullanıyorsanız, taahhüt mesajını herkesin (ve kendinizin) belirli bir zamanda ve daha önemlisi ne yaptığınızı bilmelerini sağlamak için kullanabilirsiniz.

Herhangi bir dokümantasyondan kaçınmak istediğiniz gibi yorum yazmaktan kaçınmak istersiniz. Programlama diline gelince, herkes aynı kelime hazinesi ve sözdiziminden (neredeyse) çalışır.

Uygulamanız belirli bir etki alanı için olduğunda, herkesin ortak bir kelime haznesi üzerinde hemfikir olmak ve / veya ortak bir kelime haznesi oluşturması zor olabilir. Kısaltmalar ve kapsamlı bir jargondan kaçınmamız öğretildi, ama ben onu arayacağım

FAVÖK

ve yok

EquityBeforeInterestTaxesDepreciationAndAmortization

Birini tanımıyorsanız, muhtemelen diğerini anlamıyorsunuzdur. Eğer şirket bazı olağandışı bir uygulamaya sahipse, yorum, etki alanında deneyime sahip olan ancak bu belirli firmada olmayan bir sonraki programcıya yardımcı olacaktır (Bu sadece işleri daha karmaşık hale getirir).

Kodun dokümantasyonu ile ifade edilebilirliği arasında ayrım yapmamız gerektiğini düşünüyorum .

Kod hatalarını ayıklarken veya gözden geçirirken bir kitap okumuyorsunuz. Çoğu zaman, sadece çalışma zamanında neler olup bittiğini temel olarak anlamak için yöntemden metoda atlamak ve zihninizde hızlı bağlantılar kurmak istersiniz. Kodun belgelenmesi değil, bu süreçte önemli olan kod imzalarının ifadesi , hemen tanımlayabilmeniz ve kendi dahili arama yığınınıza ekleyebilmeniz için yeterince anlamlı olma yetenekleridir. Bu noktada, beynimiz (en azından benimki bu şekilde çalışır;)) büyük yorum bloklarını bir yardımdan çok bir gürültü olarak görme eğilimindedir. Bu nedenle, tek satırlık yorumlar veya daha da iyisi, sadece kendini tanımlayıcı yöntem ve nesne adları burada yeterlidir.

Belirli bir sınıfın veya özelliğin "kitabını okumak" istiyorsanız, bunun için çok daha iyi bir yer birim testlerindedir. İyi tasarlanmış ünite testleri, doğası gereği açıklayıcıdır ve bu kodun ne yapması gerektiği ve 2 / kontrol etme kabiliyetinin tam olarak ne olduğu ile ilgili beklentileri içerdiğinden, yorum bloklarının en kalınından çok daha fazla dokümantasyon (yani açıklayıcı, ayrıntılı). Bu beklentiler gerçek koda aykırıdır. Başarılı bir sınav, dökümantasyondaki herhangi bir yorumdan yüz kat daha güvenilirdir, çünkü iddia ettiği şeyin doğru olduğunu kanıtlar.

Bazı kodlar sadece kendi kendini belgelendirmez ve bu parçayı anlayan ve test eden diğer bir insandan bazı yorumlar gerektirir. Aşağıda sahip olduğum şeyi anlamak için yeterli değil bence.

//
// iterative version
//
Node* ReverseList( Node ** List ) 
{

  Node *temp1 = *List;
  Node * temp2 = NULL;
  Node * temp3 = NULL;

  while ( temp1 )
  {
    *List = temp1; //set the head to last node 
    temp2= temp1->pNext; // save the next ptr in temp2
    temp1->pNext = temp3; // change next to privous
    temp3 = temp1;
    temp1 = temp2;
  }

  return *List;
}

Ben genellikle kodun kendisinin tamamen belgelenmeyeceğini düşündüğümden, net olmayan yerlerde yorumlar yaparak kendi kendini belgeleyen kod yazmayı tercih ederim.

Üniversitede, bir yorum ile İngilizce'deki her kod satırını hemen hemen yeniden yazmamız öğretildi (muhtemelen sadece bir şeyi kopyalamak / yapıştırmak ve en iyisini ummak yerine, aslında kodun gerçekte ne yaptığını anlama alışkanlığı haline getirmek için).

Şahsen, kodunuzun kodunu cehenneme çevirdiğini, sadece yorumlar veya kodlardan daha az okunabilir kıldığını düşünüyorum . Ben bir C # kodlayıcısıyım ve her zaman yaptığım tek yorum, IntelliSense dokümantasyonuna geri çevrilen "üçlü çizgi" yorum blokları. Bir şeyi yapmanın belirli bir yolu hakkında özellikle suçlu hissediyorsam, orit özellikle şifreli görünüyorsa, daha fazla açıklama yapacağım, ama bununla ilgili.

IMO: Kendini belgeleyen kod, değişken ve yöntem adlarına anlamlı ve bağlamsal adlar verilen koddur, böylece amaçlarının ne olduğunu açıklarlar.

Kodunuzu birden çok kez tekrar ziyaret ettiyseniz ve niyeti etki alanını bilen birisine niyeti netleştirmenin bir yolunu bulamadıysanız. Fonksiyonu yeniden yazın. Sonuçta 10-20 satırdan fazla değil. Fonksiyonu ne kadar uzun süre yeniden yazarsa, o kadar uzundur ve bu okunamaz durumda olmasının bir parçasıdır :) durulama-tekrar

ve muhtemel olmayan bir durumda, kodun ne yaptığını hala belirsiz ve akranlarınızdan yardım istemeyi hatırladığınızdan emin olabilirsiniz. Peki o zaman hepimiz Linux geliştirmeye yardım ettiğiniz için teşekkür ederiz çünkü doğru yazdığınız çekirdek kodudur? Durulama yapmazsanız en baştan tekrarlayın :)

Basitçe söylemek gerekirse yorum yazmıyorsunuz

Kod tamamlandı 2. baskı, sayfa 128-129.

Özet Veri Tipleri sizi bu bilmeceden kurtaracaktır. Kendini belgeleme kodu gitmek yoludur. Yorumlar faydalı olabilir, ancak

düşük seviyeli uygulamalar yerine gerçek dünyadaki varlıklar

yorum kullanmaktan kaçınabiliyorsunuz.

Yorumlarla ilgili bir şey, onları bir kez yazmanız, ancak işlevi uygularken görmemeniz, yalnızca işlevi değiştirdiğinizde görmenizdir.

Yorumlar, IDE tarafından Delphi 2009+ veya JavaDoc'un çalışma şekliyle yorumlandıklarında gerçekten kullanışlıdır, ancak bu daha çok yapılandırılmış bir biçimlendirme dilidir, yani bir anlamda belgelerinizi programlıyorsunuz, bu çok zekicedir.

Mantranın, kodun kendisini belgelemediğine inanıyorum, çünkü dünyadaki en iyi programcı olabilirsiniz (Ada), ancak neler olup bittiğiyle ilgili bir şey anlamadınız, ancak neden ve bir dereceye kadar belgeliyorsanız Kodunuz ne yapıyorsa onu, gelecekte kendinize ve başkalarına yardım edeceksiniz.

Yorumlar bir zorunluluktur vardır. Çünkü, kod yazarken, mevcut ihtiyaçlarınız için yazıyorsunuz, ancak gelecekte kodunuzu okumak zorunda olan insanlar için, wtf, ne yapıyorsunuz ve neden ve sonra da bunun için nasıl değişiklik yapılacağına karar veriyorsunuz.

Bunu aklınızda tutarsanız, kodlama / programlama yaparken?

Üzerinde çalışacağım bu kodun gelecekteki kodlayıcıları için bunu anlamayı ve değiştirmeyi nasıl kolaylaştırabilirim, o zaman iyi bir iş çıkacaksınız. Bunu başaramazsan, başkalarının kodunu değiştirmesini zorlaştırman ... ... ve asla böyle bir şey olmayacağını hayal etme.

İşimin çoğunda, her zaman diğer kişilerin kodlarını değiştirmek zorunda kaldım ve en korkunç biçimde yazılmış, kötü bir şekilde belgelendi.

Yani kod dökümanını kendin düşünme alışkanlığınız, sadece gereken özeni göstermiyor.

Programcının tecrübesiyle, deneyimsiz programcılara tamamen göründüğü düşünülen öz disiplini uygulamalıyız, ancak başkalarının kuralları ile yaşadığımız tüm korkunç deneyimlerden kaçınmak için alışkanlıkları olmalı. Hatta yıllar sonra kendi yasalarımıza bile bakabilirsiniz.

Check out http://thedailywtf.com onlar sadece kendi durum tespiti yapmadı programcı en ilgili esprili ama gerçek hikayeleri ton var ..