Kendini belgeleyen kod nedir ve iyi belgelenmiş kodun yerini alabilir mi? [kapalı]

Kodunun yorumlara ihtiyaç duymadığı konusunda ısrar eden bir meslektaşım var, "kendini belgeleme"

Kodunu inceledim ve başkalarının ürettiğini gördüğüm koddan daha açık olsa da, yine de kendi kendini belgeleyen kodun tam ve kullanışlı olduğu gibi yorumlanmış ve belgelenmiş kod olduğunu kabul etmiyorum.

Onun bakış açısını anlamama yardım et .

• Kendini belgeleyen kod nedir
• Gerçekten iyi yorumlanmış ve belgelenmiş kodun yerini alabilir mi
• İyi belgelendirilmiş ve yorumlanmış koddan daha iyi olduğu durumlar var mı
• Kodun yorum yapmadan kendi kendini belgeleyemeyeceği örnekler var mı?

Belki de bu sadece benim kendi sınırım, ama bunun nasıl iyi bir uygulama olabileceğini görmüyorum.

Bu bir argüman değildir - lütfen iyi yorumlanmış ve belgelenmiş kodun yüksek önceliğe sahip olmasının nedenlerini gündeme getirmeyin - bunu gösteren birçok kaynak var, ancak akranlarıma ikna olmuyorlar. Onu başka türlü ikna etmek için bakış açısını daha iyi anlamam gerektiğine inanıyorum. Gerekirse yeni bir soru başlatın, ancak burada tartışmayın.

Vay canına, hızlı tepki! Cevabınız gerçekten diğer tüm cevaplardan önemli ölçüde farklı değilse, lütfen mevcut tüm cevapları okuyun ve yeni cevaplar eklemek yerine cevaplara yorum sağlayın.

Ayrıca, kendi kendini belgeleyen koda karşı tartışanlarınız, bu öncelikle kendi kendini belgeleyen kod evangelistlerinin perspektifini (yani olumlu yönlerini) anlamama yardımcı olmaktır. Eğer konu üzerinde kalmazsanız başkalarının sizi küçümseyeceğini umuyorum.

Bence, herhangi bir kod kendi kendini belgelemelidir. İyi, kendi kendini belgeleyen kodlarda, her tanımlayıcının (değişken, yöntem, sınıf) açık bir semantik adı olduğu için her satırı açıklamanız gerekmez . Gerekenden fazla yorum yapmak aslında kodu okumayı zorlaştırır (!), Bu yüzden meslektaşınız

• her sınıf, üye, tür ve yöntem için dokümantasyon yorumları (Doxygen, JavaDoc, XML yorumları vb.) yazar VE
• kodun olmayan kısımlarını açıkça yorumlar kendi kendini belgeleyen VE
• her kod bloğu için amacı veya kodun daha yüksek bir soyutlama düzeyinde ne yaptığını açıklayan bir yorum yazar (yani bir dizindeki tüm dosyalar arasında döngü yerine 10 MB'tan büyük tüm dosyaları bul , dosya boyutunun 10'dan büyük olup olmadığını test et MB, doğruysa getiri getirisi )

bence kodu ve dokümantasyonu gayet iyi. Not Kendi belgelenmiş kod anlamına değil hiç yorum olmaması gerektiğini, ancak hiçbir gereksiz yorumlar olmamalıdır sadece anlamına gelir. Bununla birlikte, kodu okuyarak (yorumlar ve dokümantasyon yorumları dahil), kodun ne yaptığını ve nedenini hemen anlaması gerekir. "Kendini belgeleyen" kodun anlaşılması yorumlanan koddan daha uzun sürüyorsa, gerçekten kendiliğinden belgelenmez.

Peki, bu yorumlar ve kodla ilgili olduğundan, bazı gerçek koda bakalım. Bu tipik kodu karşılaştırın:

float a, b, c; a=9.81; b=5; c= .5*a*(b^2);

Ne yapıldığını gösteren bu kendi kendini belgeleyen koda :

const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

Ve sonra, neden yapıldığını daha iyi açıklayan bu belgelenmiş koda :

/* compute displacement with Newton's equation x = vₒt + ½at² */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

Ve sıfır yorum içeren belgeler olarak kodun son sürümü gerekli:

float computeDisplacement(float timeInSeconds) {
    const float gravitationalForce = 9.81;
    float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);
    return displacement;
}

Kötü yorum stiline bir örnek:

const float a = 9.81; //gravitational force
float b = 5; //time in seconds
float c = (1/2)*a*(b^2) //multiply the time and gravity together to get displacement.

Son örnekte, yorumlar değişkenlerin tanımlayıcı olarak adlandırılması gerektiğinde kullanılır ve işlemin ne olduğunu açıkça görebildiğimizde bir işlemin sonuçları özetlenir. Her gün bunun için kendi kendini belgeleyen ikinci örneği tercih ederim ve belki de arkadaşınızın kendi kendini belgelediği kod söylediği zaman budur.

Bunun ne yaptığınızın bağlamına bağlı olduğunu söyleyebilirim. Benim için, bu durumda kendi kendini belgeleyen kod muhtemelen yeterlidir, ancak arkasında yapılanların (bu örnekte denklem) arkasındaki metodolojiyi detaylandıran bir yorum da yararlıdır.

Kodun kendisi her zaman kodunuzun ne yaptığının en güncel açıklaması olacaktır, ama bence yorumların en önemli yönü olan amacı açıklamak çok zordur . Düzgün yazılmışsa , kodun ne yaptığını zaten biliyoruz , sadece dünyada neden yaptığını bilmemiz gerekiyor!

Birisi bir keresinde dedi ki

1) Sadece anlaşılması zor olan kod için yorumlar yazın.
2) Anlaması zor kod yazmamaya çalışın.

"Kendini belgeleme" kodunun arkasındaki fikir, koddaki gerçek program mantığının, kodu okuyan herkese sadece kodun ne yaptığını değil, neden yaptığını açıklayacak kadar açık olmasıdır.

Bence, gerçek kendini belgeleyen kod fikri bir efsanedir. Kod size olan bitenin arkasındaki mantığı söyleyebilir, ancak neden belirli bir şekilde yapıldığını açıklayamaz , özellikle de bir sorunu çözmenin birden fazla yolu varsa. Bu nedenle, tek başına iyi yorumlanmış kodların yerini alamaz .

Belirli bir kod satırının kendi kendini belgelendirip belgelemediğini sormakla ilgili olduğunu düşünüyorum, ancak sonunda bir kod diliminin yapısını ve işlevini anlamadıysanız, çoğu zaman yorumlar yardımcı olmayacaktır. Örneğin, amdfan'ın "doğru yorumlanmış" kod dilimini ele alalım:

/* compute displacement with Newton's equation x = v0t + ½at^2 */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

Bu kod iyidir, ancak aşağıdakiler çoğu modern yazılım sisteminde eşit derecede bilgilendiricidir ve Newtonian hesaplamanın kullanılmasının, diğer bazı fiziksel paradigmaların daha uygun olması durumunda değiştirilebilecek bir seçenek olduğunu açıkça kabul eder:

const float accelerationDueToGravity = 9.81;
float timeInSeconds = 5;
float displacement = NewtonianPhysics.CalculateDisplacement(accelerationDueToGravity, timeInSeconds);

Kendi kişisel deneyimime göre, kesinlikle yorumlara ihtiyaç duyduğunuz çok az "normal" kodlama durumu vardır. Örneğin, kendi algoritmanızı ne sıklıkla yuvarlarsınız? Temelde diğer her şey, bir kodlayıcının kullanımdaki yapıları ve sistemi bu belirli yapıları kullanmak için yönlendiren seçenekleri anlayabilmesi için sisteminizi yapılandırma meselesidir.

Bunu nereden aldığımı unuttum, ama:

Bir programdaki her yorum okuyucu için bir özür gibidir. "Kodumun o kadar opak olduğu için üzgünüm, ona bakarak anlayamazsınız". Sadece mükemmel olmadığımızı kabul etmeliyiz, ancak mükemmel olmaya çalışıyoruz ve gerektiğinde özür dilemeye devam ediyoruz.

Her şeyden önce, meslektaşınızın kodunun aslında gördüğünüz diğer kodlardan daha net olduğunu duymak güzel. Muhtemelen “kendi kendini belgeleme” yi, kodunu yorumlamak için çok tembel olmak için bir bahane olarak kullanmıyor demektir.

Kendini belgeleyen kod, bilgili bir okuyucunun ne yaptığını anlaması için serbest metin yorumları gerektirmeyen koddur. Örneğin, bu kod parçası kendi kendini belgeliyor:

print "Hello, World!"

ve böylece:

factorial n = product [1..n]

ve böylece:

from BeautifulSoup import BeautifulSoup, Tag

def replace_a_href_with_span(soup):
    links = soup.findAll("a")
    for link in links:
        tag = Tag(soup, "span", [("class", "looksLikeLink")])
        tag.contents = link.contents
        link.replaceWith(tag)

Şimdi, bu "bilgili okuyucu" fikri çok öznel ve durumsaldır. Siz veya başka biri meslektaşınızın kodunu takip etmekte sorun yaşıyorsa, bilgili bir okuyucu fikrini yeniden değerlendirmek için iyi olur. Kodun kendi kendini belgelemesini sağlamak için kullanılan dil ve kütüphanelere bir miktar aşinalık olduğu varsayılmalıdır.

"Kendini belgeleyen kod" yazmak için gördüğüm en iyi argüman, serbest metin yorumlamasının kodun yazıldığı gibi anlaşamaması sorununu ortadan kaldırmasıdır. En iyi eleştiri, kodun kendi başına ne yaptığını ve nasıl yaptığını açıklayabilmesine rağmen, bir şeyin neden belirli bir şekilde yapıldığını açıklayamamasıdır .

Kendini belgeleyen kod "KURU" ("Kendinizi Tekrarlama") için iyi bir örnektir. Kodun kendisinde bulunan veya olabilecek yorumlardaki bilgileri çoğaltmayın.

Bir değişkenin ne için kullanıldığını açıklamak yerine değişkeni yeniden adlandırın.

Kısa bir kod snippet'inin ne yaptığını açıklamak yerine, bir yönteme çıkarın ve açıklayıcı bir ad verin (belki de yorum metninizin kısaltılmış bir versiyonu).

Karmaşık bir testin ne yaptığını açıklamak yerine, bunu bir yönteme de çıkarın ve iyi bir isim verin.

Vb.

Bundan sonra, çok fazla açıklama gerektirmeyen bir kodla karşılaşırsınız, kendini açıklar, bu nedenle sadece koddaki bilgileri tekrarlayan yorumları silmeniz gerekir.

Bu, hiç yorumunuz olmadığı anlamına gelmez, koda koyamayacağınız niyet gibi bilgiler ("neden") gibi bazı bilgiler vardır. İdeal durumda, kod ve yorumlar birbirini tamamlar, her biri diğerindeki bilgileri çoğaltmadan benzersiz açıklayıcı değer katar.

kendi kendini belgeleyen kod iyi bir uygulamadır ve uygun şekilde yapılırsa çok fazla yorum okumadan kodun anlamını kolayca iletebilir. özellikle alan adının ekipteki herkes tarafından iyi anlaşıldığı durumlarda.

Bunu söyledikten sonra, yorumlar yeni gelenler veya test kullanıcıları için veya belge / yardım dosyaları oluşturmak için çok yararlı olabilir.

kendi kendini belgeleyen kod + gerekli yorumlar ekipler arası insanlara yardım etmek için çok yol kat edecektir.

Sırayla:

• Kendi kendini belgeleyen kod, okuyucuya niyetini açıkça ifade eden koddur.
• Tam olarak değil. Yorumlar her zaman neden belirli bir stratejinin seçildiğine dair yorumlar için faydalıdır . Ancak, kodun bir bölümünün ne yaptığını açıklayan yorumlar , yetersiz kendi kendini belgeleyen ve bazı yeniden düzenleme işlemlerini kullanabilen kodun göstergesidir.
• Yorumlar yalan söyler ve güncelliğini yitirir. Kod her zaman söyler doğruyu söyleme olasılığı daha yüksektir.
• Kod ne yorum olmadan yeterince açık hale getirilemedi bir dava görmedim ; ancak, daha önce de söylediğim gibi, bazen bunun nedenini açıklamak gerekir .

Bununla birlikte, gerçekten kendi kendini belgeleyen kodun çok fazla öz ve takım disiplini gerektirdiğini belirtmek önemlidir. Daha bildirici program yapmayı öğrenmelisiniz ve çok mütevazı olmalısınız ve kodun lehine "zeki" koddan kaçınmalısınız ki herkesin yazmış olabileceği açıktır.

Bir "kendi kendini belgeleyen kod" okuduğunuzda, ne yaptığını görürsünüz, ancak neden bu şekilde yapıldığını her zaman tahmin edemezsiniz.

İş mantığı, güvenlik, kullanıcı talepleri vb.Gibi programlama dışı kısıtlamalar vardır.

Bakım yaptığınızda, bu backgorund bilgileri çok önemli hale gelir.

Sadece bir tutam tuzum ...

Birincisi, aşağıdaki snippet'i düşünün:

/**
 * Sets the value of foobar.
 *
 * @foobar is the new vaue of foobar.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

Bu örnekte, 3 kod satırı başına 5 satır yorumunuz vardır. Daha da kötüsü - yorumlar kodu okuyarak göremediğiniz hiçbir şey eklemez. Bunun gibi 10 yönteminiz varsa, 'yorum körlüğü' elde edebilir ve kalıptan sapan yöntemi göremezsiniz.

Elbette, daha iyi bir sürüm olurdu:

/**
 * The serialization of the foobar object is used to synchronize the qux task.
 * The default value is unique instance, override if needed.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

Yine de, önemsiz kod için yorum yapmamayı tercih ediyorum. Amaç ve genel organizasyon, kodun dışındaki ayrı bir belgede daha iyi açıklanmaktadır.

Aradaki fark "ne" ile "nasıl" arasındadır.

• Bir rutinin "ne" yaptığını belgelemelisiniz.
• Özel durumlar olmadıkça "nasıl" yaptığını belgelememelisiniz (örn. Belirli bir algoritma kağıdına bakın). Bu kendi kendine belgelenmelidir.

Meslektaşınıza işaret etmek isteyebileceğiniz bir şey, diğer alternatif yaklaşımlar düşünülür ve bu bilgilerle kodu yorumlamadığı sürece bilgilerin kaybolacağı dikkate alınmazsa, kodunun ne kadar kendi kendine belgelendiği olursa olsun. Bazen bir alternatifin düşünüldüğünü ve neden buna karşı karar verildiğini ve kod yorumlarının zaman içinde hayatta kalma olasılığının yüksek olduğunu bilmek de önemlidir.

Çalıştığım bir şirkette programcılardan biri monitörünün üstüne yapışmıştı.

"Kodunuzu koruyan kişi gibi nerede yaşadığınızı bilen homosidal bir manyak gibi belgeleyin."

kendi kendini belgeleyen kod normalde kodun ne yaptığına tam olarak uyan değişken adları kullanır, böylece neler olduğunu anlamak kolaydır

Ancak, böyle bir "kendi kendini belgeleyen kod" hiçbir zaman yorumların yerini almayacaktır. Bazen kod çok karmaşıktır ve özellikle belgelendirilebilirlik açısından kendi kendini belgeleyen kod yeterli değildir.

Bir zamanlar bu teoriye inanan bir profesörüm vardı Aslında onu hatırladığım en iyi şey "Yorumlar sissies içindir"
İlk başta hepimizi şaşırttı ama mantıklı geldi.
Ancak durum, kodda neler olup bittiğini anlayabilmenize rağmen, arkanızdan gelip neler olduğunu anlayamadığınızdan daha az deneyimli biri olabilir. Bu, yorumların önemli hale geldiği zamandır. Birçok kez önemli olduklarına inanmadığımızı biliyorum, ancak yorumların gereksiz olduğu çok az durum var.

Kimsenin " Edebi Programlama " nın getirmediğine şaşırdım 1981 yılında TeX'ten Donald E. Knuth ve "Bilgisayar Programlama Sanatı" şöhreti tarafından geliştirilen bir teknik olan " i .

Öncül basit: kod bir insan tarafından anlaşılması ve yorumların derleyici tarafından atılması gerektiğinden, neden herkese ihtiyaç duydukları şeyi vermiyorsunuz - kodlama amacının tam bir metin açıklaması, programlama dili gereksinimleri tarafından bozulmamış , insan okuyucu için ve derleyici için saf kod.

Okuryazar Programlama araçları bunu, araçlara hangi parçanın kaynak ve ne metin olması gerektiğini bildiren bir belge için özel işaretleme yaparak yapar. Program daha sonra kaynak kod parçalarını belgeden çıkarır ve bir kod dosyası birleştirir.

Web'de bir örnek buldum: http://moonflare.com/code/select/select.nw veya HTML sürümü http://moonflare.com/code/select/select.html

Knuth'un kitabını bir kütüphanede bulabilirseniz (Donald E. Knuth, Literate Programming, Stanford, California: Dil ve Bilgi Araştırma Merkezi, 1992, CSLI Ders Notları, no. 27.) okumalısınız.

Bu, kendi kendini belgeleyen kod, akıl yürütme ve her şeyle birlikte. Hatta güzel bir belge yapar, Diğer her şey iyi yazılmış yorumlar :-)

Birçok geçerli cevaba bir bakış açısı daha sunmak istiyorum:

Kaynak kodu nedir? Programlama dili nedir?

Makinelerin kaynak koduna ihtiyacı yoktur. Montajı yapmaktan mutlular. Programlama dilleri bizim yararımız içindir. Meclis yazmak istemiyoruz. Ne yazdığımızı anlamamız gerekiyor. Programlama kod yazmakla ilgilidir.

Yazdıklarınızı okuyabilmeli misiniz?

Kaynak kodu insan dilinde yazılmamıştır. Denendi (örneğin FORTRAN) ama tamamen başarılı değil.

Kaynak kodun belirsizliği olamaz. Bu yüzden içine metinle yaptığımızdan daha fazla yapı koymalıyız. Metin yalnızca metin kullanırken verdiğimiz bağlamla çalışır. Kaynak koddaki bağlam her zaman açıktır. C # kullanarak "kullanarak" düşünün.

Çoğu programlama dili yedeklidir, böylece derleyici tutarlı olmadığımızda bizi yakalayabilir. Diğer diller daha fazla çıkarım kullanır ve bu fazlalığı ortadan kaldırmaya çalışır.

Bilgisayarlar için tür adlarına, yöntem adlarına ve değişken adlarına gerek yoktur. Referans olarak bizim tarafımızdan kullanılmıştır. Derleyici anlambilimi anlamıyor, bu bizim için.

Programlama dilleri insan ve makine arasındaki dilsel bir köprüdür. Bizim için yazılabilir ve onlar için okunabilir olmalıdır. İkincil talepler, bizim için okunabilir olması gerektiğidir. İzin verilen semantikte iyiysek ve kodu yapılandırmakta iyiysek, kaynak kodun bizim için bile okunması kolay olmalıdır. En iyi kodun yorum yapması gerekmez.

Ancak karmaşıklık her projede gizlenir, her zaman karmaşıklığı nereye koyacağınıza ve hangi develerin yutulacağına karar vermelisiniz. Bunlar yorumların kullanıldığı yerlerdir.

Kendi kendini belgeleyen kod, zaman kodu, yorum ve dokümantasyonda farklılaşan sorunun kolay bir seçimidir. Ve açık bir kod yazmak disiplin edici bir faktördür (eğer kendinize karşı katı iseniz).

Benim için uymaya çalıştığım kurallar bunlar:

• Kodun okunması mümkün olduğunca kolay ve anlaşılır olmalıdır.
• Yorumlar, aldığım tasarım kararları için nedenler vermelidir, örneğin: bu algoritmayı neden kullanıyorum veya kodun sahip olduğu sınırlamalar, örneğin: ne zaman çalışmıyor ... (bu koddaki bir sözleşmede / iddiada ele alınmalıdır) (genellikle işlev / prosedür dahilinde).
• Belgelerde kullanım (çağrı konferansları), yan etkiler, olası dönüş değerleri listelenmelidir. JDoc veya xmlDoc gibi araçlar kullanılarak koddan çıkarılabilir. Bu nedenle, genellikle işlevin / yordamın dışında, ancak açıkladığı koda yakındır.

Bu, kodu belgelemenin üç yolunun da birbirine yakın yaşadığı ve bu nedenle kod değiştiğinde değiştirilme olasılığının daha yüksek olduğu, ancak ifade ettikleri şeyle çakışmadığı anlamına gelir.

Kendi kendini belgeleyen kodla ilgili gerçek sorun, aslında ne yaptığını iletmesidir. Bazı yorumlar birisinin kodu daha iyi anlamasına yardımcı olabilirken (örn. Algoritma adımları vb.) Bir dereceye kadar gereksizdir ve eşinizi ikna edeceğinizden şüpheliyim.

Bununla birlikte, dokümantasyonda gerçekten önemli olan şey, koddan doğrudan belirgin olmayan şeylerdir: temel amaç, varsayımlar, etkiler, sınırlamalar, vb.

Bir kodun X'i hızlı bir bakışta yaptığını belirleyebilmek, bir kodun Y'nin yapmadığını belirlemekten çok daha kolaydır.

Ona iyi görünen, açık bir kod örneği gösterebilirsiniz, ancak aslında girdinin tüm temellerini kapsamıyor ve onu bulup bulamayacağını görüyorsunuz.

Kendini belgeleyen kodun yorum yapmak için iyi bir yedek olduğunu düşünüyorum. Kodun nasıl veya neden böyle olduğunu açıklamak için yorumlara ihtiyacınız varsa, daha açıklayıcı olması için değiştirilmesi gereken bir işlev veya değişken adlarınız vardır. Bir açıklama ile eksikliği telafi edip etmeyeceği veya bazı değişkenleri ve işlevleri yeniden adlandırma ve kodu yeniden düzenleme ile ilgili olabilir.

Belgelerinizin yerini tutamaz, çünkü belgeler sisteminizi nasıl kullanacağınızı açıklamak için başkalarına verdiğiniz şeydir.

Düzenleme: Ben (ve muhtemelen herkes) muhtemelen bir Dijital Sinyal İşleme (DSP) uygulaması çok iyi yorumlanması şartı olmalıdır. Bunun nedeni, DSP uygulamalarının temelde değer dizileri ile beslenen döngüler için 2 olması ve belirtilen değerleri ekler / çoğaltır / vb. bu durumda yapıyorsunuz;)

Matematiksel kod yazarken, bazen matematiği, kodun kullandığı gösterimsel kuralları ve hepsinin birbirine nasıl uyduğunu açıklayan uzun, kompozisyon benzeri yorumlar yazmayı yararlı buldum. Burada yüzlerce satırdan bahsediyoruz.

Kodumu olabildiğince kendi kendine belgelemeye çalışıyorum, ancak birkaç ay sonra üzerinde çalışmaya geri döndüğümde, bir karma yapmaktan kaçınmak için açıklamayı okumam gerekiyor.

Şimdi, elbette, bu tür aşırı önlemler çoğu durumda gerekli değildir. Hikayenin ahlaki olduğunu düşünüyorum: farklı kod farklı miktarda dokümantasyon gerektirir. Bazı kodlar o kadar açık bir şekilde yazılabilir ki bu da yorumlara ihtiyaç duymaz - bu yüzden açıkça yazın ve yorumları kullanmayın!

Ancak birçok kodun mantıklı olması için yorumlara ihtiyacı vardır, bu yüzden mümkün olduğunca net bir şekilde yazın ve sonra gerektiği kadar yorum kullanın ...

Birçoğunuzun yaptığı gibi - gerçekten kendi kendini belgelemek için, kodun bir tür niyet göstermesi gerektiğini savunuyorum. Ama henüz kimsenin BDD'den bahsetmediğine şaşırdım - Davranış Odaklı Gelişim . Fikrin bir kısmı, kodunuzun amacını açıklayan otomatik testlere (kod) sahip olmanızdır, aksi takdirde bunu açıkça belirtmek çok zordur.

İyi alan adı modelleme 
+ iyi adlar (değişkenler, yöntemler, sınıflar) 
+ kod örnekleri (kullanım senaryolarından birim testleri) 
= kendi kendini belgeleyen yazılım 

Kodun yanı sıra ekstra yorumların daha net olmasının birkaç nedeni:

• Bakmakta olduğunuz kod otomatik olarak oluşturuldu ve bu nedenle proje üzerinde bir sonraki derleme işleminde kodda yapılacak herhangi bir düzenleme zorlanabilir
• Daha az basit bir uygulama, bir performans kazancı için işlem görmüştür (bir döngüyü açmak, pahalı bir hesaplama için bir arama tablosu oluşturmak vb.)

Her şey ekibin belgelerinde değer verdiği şey olacak. Ben nasıl önemli / niçin önemini belgelemek ve bu her zaman kendi kendini belgeleme kodu yakalanmayan öneririz. olsun / ayarlayın hayır bunlar açık - ama hesaplama, alma vb neden bir şey ifade edilmelidir.

Ayrıca farklı milletlerden geliyorsanız takımınızdaki farkın farkında olun. Diksiyondaki farklılıklar, yöntemlerin adlandırılmasına neden olabilir:

BisectionSearch

Ikili arama

BinaryChop

3 farklı kıtada eğitim almış geliştiricilerin katkıda bulunduğu bu üç yöntem de aynı şeyi yapıyor. Sadece algoritmayı tarif eden yorumları okuyarak kütüphanemizdeki kopyalamayı belirleyebildik.

Benim için yorum gerektiren kodu okumak bilmediğim dilde metin okumak gibidir. İfadeyi görüyorum ve ne yaptığını ya da nedenini anlamıyorum - ve yorumlara bakmak zorundayım. Bir cümle okuyorum ve ne anlama geldiğini anlamak için sözlüğe bakmam gerekiyor.

Yaptıklarını kendi kendine belgeleyen bir kod yazmak genellikle kolaydır. Neden böyle olduğunu söylemek için yorumlar daha uygundur, ancak burada bile kod daha iyi olabilir. Sisteminizi her soyutlama düzeyinde anlarsanız, kodunuzu aşağıdaki gibi düzenlemeyi denemelisiniz

public Result whatYouWantToDo(){
  howYouDoItStep1();
  howYouDoItStep2();
  return resultOfWhatYouHavDone;
}

Yöntem adının amacınızı yansıttığı ve yöntem gövdesi, hedefinize nasıl ulaştığınızı açıklar. Yine de kitabın tamamını başlığında söyleyemezsiniz, bu nedenle sisteminizin ana soyutlamalarının yanı sıra karmaşık algoritmalar, önemsiz olmayan yöntem sözleşmeleri ve eserler belgelenmelidir.

Eğer meslektaşınızın ürettiği kod gerçekten kendi kendini belgeliyorsa - siz ve onun için şanslısınız. Eğer meslektaşlarınızın kodunun yorumlara ihtiyacı olduğunu düşünüyorsanız - gerekir. Sadece içindeki en önemsiz yeri açın, bir kez okuyun ve her şeyi anlayıp anlamadığınızı görün. Kod kendi kendini belgeliyorsa - yapmalısınız. Değilse - meslektaşınıza bu konuda bir soru sorun, size bir cevap verdikten sonra, bu cevabın neden yorumlarda veya kodda önceden belgelenmediğini sorun. Kodun kendisi gibi akıllı bir kişi için kendi kendine belge olduğunu iddia edebilir, ancak yine de diğer ekip üyelerine saygı duymalıdır - görevleriniz kodunu anlamayı gerektiriyorsa ve kodu size anlamanız gereken her şeyi açıklamıyorsa - ihtiyacı var yorumlar.

Çoğu dokümantasyon / yorum, gelecekteki kod geliştiricilerine / geliştiricilere yardımcı olmaya hizmet eder ve bu nedenle kodu sürdürülebilir kılar. Çoğu zaman yeni özellikler eklemek veya optimize etmek için modülümüze daha sonra geri döneceğiz. O zaman, sadece yorumları okuyarak kodu anlamak çok sayıda kesme noktasından geçmekten daha kolay olurdu. Ayrıca, mevcut mantığı deşifre etmekten ziyade yeni mantık düşünmek için zaman harcamayı tercih ederim.

Bence o ne olabilir yorum kodun ne yaptığını açıklarsa niyetinin ne olduğunu net olması için yeniden yazılması gerektiğini olduğunu düşünüyorum. Kodu kendi kendine belgeleyerek bunu kastediyor. Genellikle bu, uzun işlevi basitçe tanımlayıcı işlev adına sahip mantıksal küçük parçalara bölmek anlamına gelebilir.

Bu, kodun yorumlanmaması gerektiği anlamına gelmez. Bu, yorumların kodun olduğu gibi yazılmasının bir nedenini sağlaması gerektiği anlamına gelir.

Ben her zaman kendi kendine belgeleme kodu elde etmek için çaba gerektiğini inanıyorum çünkü kod okumayı kolaylaştırır. Ancak, bazı şeyler hakkında pragmatik olmalısınız.

Örneğin, genellikle her sınıf üyesine bir yorum ekliyorum (bunun için dokümantasyon yorumlarını kullanıyorum). Bu, üyenin ne yapması gerektiğini açıklar ancak nasıl yaptığını açıklamaz. Ben kod, özellikle eski kod aracılığıyla okurken, bu üyenin ne olduğunu hızlı bir şekilde hatırlamama yardımcı olduğunu bulmak ve ben de kod okuma ve çalışma dışarı, özellikle kod akışı biraz etrafında atlar, daha kolay buluyorum .

Bu sadece benim görüşüm. Yorum yapmadan çalışan birçok insan tanıyorum ve bunun sorun olmadığını söylüyorlar. Bununla birlikte, birisine altı ay önce yazdıkları bir yöntemi sordum ve bana tam olarak ne yaptığını söylemek için birkaç dakika düşünmeleri gerekiyordu. Yöntem yorumlanırsa bu bir sorun oluşturmaz.

Son olarak, yorumların aynı şekilde kod olarak sistemin bir parçası olduğunu hatırlamanız gerekir. Yeniden düzenleme ve işlevselliği değiştirme gibi yorumlarınızı da güncellemeniz gerekir. Bu, yanlış kullanıldıklarında işe yaramaz olmaktan daha kötü oldukları için yorumları kullanmaya karşı bir argüman.