Kod kendini belgeliyor mu? [kapalı]

Bu, uzun yıllar önce bana bir iş görüşmesinde mezun olarak ortaya konan bir soru ve şimdi ve tekrar beynime düştü ve beni gerçekten tatmin eden iyi bir cevap bulamadım.

Söz konusu görüşmeci siyah beyaz bir cevap arıyordu, ortada bir zemin yoktu. Sorunun ardındaki mantık hakkında soru sorma şansım olmadı, ama merak ediyorum ki bu soru bir geliştiriciye niçin konulacak ve evet ya da hayır cevabından ne öğreneceksiniz?

Kendi bakış açıma göre, Java, Python, Delphi vb. beni vurmaya başlarsın, bunu birkaç ofisin geliştiricileri tarafından söylendiğini duydum), bu tam olarak nasıl kendini belgeliyor? Bu soru garip görünüyorsa özür dilerim, ancak bir röportajda neden birine konulacağına dair daha iyi bir anlayış elde etmek için bazı sorular sormayı ve fikir almayı tercih ederim.

Kısmen.

Büyük İngilizce Kelimeler kullanan kod, kısmen tüm işlevleri ve değişkenlerin adlarının ne yaptığını size söyleyebilmesi için kendi kendini belgeleyebilir. Ama muhtemelen nedenini size söylemeyecek.

Karşılaştırmak:

a->b;
# what is b doing? what is the a object?

carEngine->startIgnition;
# much more clear what objects are involved

Ama hala bir arabanın neden çalıştırıldığını bilmiyorsun. Dolayısıyla, sadece kısmen. Görüşme yapan kişiden siyah beyaz bir cevap beklemekteydi, siyah ve beyaz görüşlerini belki de çok kuvvetli içermiyorsa, bu korkunç bir şey.

Hayır. Kod kendi içinde belgelenmiyor.

Bunun nedeni, kodun NASIL olduğunu belirtir ve bu kodu korumak için insanların bilmesi gereken WHY'yi umursamaz .

Bu yüzden neden tüm WHY'leri açıklayan ek yorumlara ihtiyacınız var . Değişken isimlerinizin kararların bir bölümünü içermesine izin vererek onları sınırlayabilirsiniz, ancak bunlardan kaçınamazsınız.

Doğru kod size " nasıl " olduğunu söyler . Doğru yorumlar size " neden " olduğunu söyler .

Bu nedenle kod, işlerin başarılma şeklini kendi kendine belgeliyor olabilir, ancak bunun nedenini belgelediğini varsayamazsınız.

Siyah beyaz bir cevapta ısrar ediyorlarsa, orta temasa izin verilmez, cevap hayırdır.

Daha kesin cevap, kodun makul olan en yüksek düzeyde kendi kendini belgelendirmesi gerektiğidir, ancak koda bazı türdeki dokümanları dahil etmenin makul bir yolu yoktur. Örneğin, kod yalnızca A formunda hangi bilgilerin toplandığını, B formunda ve C formunda hangi bilgilerin toplandığını belgelemek için bir ceza verebilir. bu şekilde veriler, üç yerine sadece iki form kullanarak (örneğin) ile karşılaştırıldığında hataları% x azalttı.

En önemsiz kod parçası dışında herhangi bir şey, en azından bazı dış dokümantasyonlardan yararlanabilir.

Cevabım. Mümkün olduğunca, kodunuzu olabildiğince kendiliğinden belgelemek için çaba göstermelisiniz. Bunun için birçok nedeni vardır. İlk yazıldığında, 10 satırındaki ortalama bir satırda bir hata var. Koddaki hatalar bulunup giderilme eğilimindedir. Dokümantasyondaki hatalar bırakılma eğilimindedir. Bakım sırasında, kod ve belgelerin birbirinden ayrılması yaygındır.

Bununla birlikte, kodun açıklığa kavuşturulması ile yapılabileceklerin sınırlı olduğu söylenebilir. Bu gibi durumlarda, belgelendirmelisiniz.

Belgelendirme konusunda tercihiniz olan dava ne olacak? Benim görüşüme göre bakım kurumunuza büyük ölçüde bağlıdır. Mükemmel bir yazılım geliştiriciniz ve titiz bir kod inceleme süreciniz varsa (örneğin Google’ın yaptığı gibi), işleminiz ve kişileriniz, sürdürülmeyen yorumlar konusunda endişelenmenize gerek kalmayacak şekilde olabilir. Bu durumda daha ağır bir yorum tarzı çok mantıklı. (Google, aslında yorum ağırlıklı bir tarza sahiptir.) Ancak daha tipik bir kuruluşunuz varsa, o zaman gördüğüm herhangi bir yorumu çok fazla güvensizleştireceğim ve umarınıza inanan insanlara sahip olduğunuzu umuyorum. kendi kendini belgeleyen kod yapmaya çalışıyorum. Bu durumda yorumları gereksiz göreceğim.

Yorumlamanın esası ve dezavantajları hakkında ilginç bir sohbet için, parçası olduğum eski bir sohbet için http://www.perlmonks.org/index.pl?node_id=65153 adresine bakın . (Unutmayın, aynı zamanda bu sohbeti yaptık, arkadaşça olan özel bir sohbet grubu vardı. Her zaman sohbetimin sadece daha olumsuz yarısının halka açık olduğu için pişman oldum.) Düşüncelerim artık o zaman düşündüğümle tam olarak eşleşmiyor. ama yine de konuşmanın düşünce için değerli yiyeceklere sahip olduğunu düşünüyorum.

Bu sorunun çok fazla ortaya çıktığını ve bununla ilgili genellikle dini bir endişeye sahip olduğunu buluyorum. İşte benim aldığım şey ...

İdeal bir dünyada aşağıdaki ifade yapılabilir:

Kod, mantığın yorumlamaya gerek kalmadan takip edilebileceği şekilde yazılmalıdır.

Tamam, bu yeterince adil, ancak sorun şu ki ideal bir dünyada yaşamıyoruz. Bu ideal ifadeye ulaşmada bazı sorunlar var.

1. Programcılar genellikle karşı programladıkları sektördeki uzmanlar değildir. startEngine(Car car)Herkesin burada ne istendiğini anlayabilmesi gibi bir işlevi anlamak yeterince kolaydır . Ama gerçek dünyaya taşın, işler biraz daha karışır. Örneğin, işlev getSess(String tid, String aid)DWDM sistemlerini anlayan bir nakliye mühendisi tarafından kusursuz bir şekilde anlaşılabilir ancak projeye yeni giren programcı için bir zorluk olabilir. İyi yerleştirilmiş yorumlar, kodu zamanında anlamanın geçişini kolaylaştırmaya yardımcı olabilir.

2. Kodu korumak isteyen programcılar genellikle kodun orijinal mimarları kadar yetenekli değildir. Orijinal programcı, belirli bir görevi yerine getirmek için hızlı, özlü ve etkili bir algoritma yazabilecek kadar yetenekli olabilir. Ancak programcı, bu kodu sürdürme görevini, neler olduğunu anlamaya çalışmakla mücadele edebilir. İyi yerleştirilmiş yorumlar, kodu zamanında anlamanın geçişini kolaylaştırmaya yardımcı olabilir.

3. Kaç kez kod yazdınız, daha sonra neden yaptığınızı, hatta neyi başarmaya çalıştığınızı anlamak için mücadele ettiniz? Hepimiz bunu zaman zaman yapıyoruz. Bir problem çözme ve bir problemin çözümü için kolay bir çözüm üretmek genellikle iki farklı zihniyettir. Geçitten mükemmel bir şekilde kod yazabilen kişi olmadığınız sürece, devam ederken kodunuzla ilgili birçok yanlış adım atıyorsunuz. Ayrıca bir süre için bu kod parçasına geri dönemeyebilirsiniz. İyi yerleştirilmiş yorumlar, kodu zamanında anlamanın geçişini kolaylaştırmaya yardımcı olabilir.

4. Eşsiz durumlar açıklama gerektirir. Örneğin, bir programcı neden 100ms'lik bir duraklamanın bir DWDM cihazıyla iletişim kuran bir parça koya girdiğini merak edebilir. Bir sonraki programcıya, cihazın alımı yavaşladığından ve komutu kaçırabileceğinden bir duraklamanın gerektiğini bilmesini sağlamak, sahip olunması gereken değerli bir bilgi olacaktır. İyi yerleştirilmiş yorumlar, kodu zamanında anlamanın geçişini kolaylaştırmaya yardımcı olabilir.

Güzel yazılmış, "kendini belgeleyen" kodunu bulmak bir zevktir. Güzel yazılı, "kendi kendini belgeleyen" kod, ile iyi yerleştirilmiş, bilgilendirici yorumlar bir ganimet ve çok nadir bulmak olduğunu.

Sadece ilk sorunun her tarafında tartışmalar yapmak için:

Evet, kod kendi kendine belgelendiriliyor. Değişkenler, yöntemler ve sınıf adlarının tümü, bu bir kişisel belgeleme biçimi olması için okunması ve anlaşılması kolay olabilir. Kod stilinde, sonunda standart prosedür olarak kabul edilen XML belgelerini veren bir şey olabilir. Başka bir deyişle, kodla karıştırılabilecek belgeler sunmak geliştiricinin işinin bir parçasıdır.

Hayır, kod kendiliğinden belgelenmiyor. Alınan iş kararları, tasarım seçimleri yapıldı ve diğer faktörler kod satırında görünmeyecek ve kod tabanının dışına yazılmalıdır. Bu nedenle dış dokümantasyon gereklidir ve bunlar bunun örnekleridir.

Sorma noktası: Bir cevabın sınırlarını tanıyan kısmi bir cevap verir misiniz yoksa hangi tarafın daha iyi bir uygulama olduğuna inandığınıza körü körüne yaslanır mısınız? Cevabınız evet mi yoksa hayır mı diye ne kadar mahkumiyetiniz var? Cevap verebilecek birinden yükselmek için tasarlanmış stresli bir soru olarak görülebilir, "Ne ...? Bana sorabileceğiniz en aptalca soru. Hakaret ettiği gerekçesiyle cevaplamayı reddediyorum. zekanı inancın ötesinde! daha kibirli ve görkemli bir cevap olarak bazı insanların bu tonda cevap verdiğini hayal edebiliyorum.

Belli ki Knuth tarzında okuryazar bir programcıydı . Bir LP öğrencisine kodun geçerli olması için kendi kendini belgelemesi gerekir. Yani olası tek cevap "evet".

Buradaki sorun, okuryazar bir çok programlama dili olmaması ve yaygın olarak kullanılan ticari kullanımda bilmediğim bir şey olmaması. Bu yüzden bir yerlerde bir niş pozisyon olması gerekirdi.

Görüşme yapan kişinin aradığı şey şudur: "Kendini belgeleme kodunu nasıl yazıyorsunuz?" ima ile "Belgelendirme konusundaki tutumunuz nedir?"

Robert C Martin adında bir adam tarafından ilham verici bir konferansa gittim ve bir keresinde Clean Code kitabının 'yazma yöntemleri' hakkında konuştu.

Açıkçası biraz daha saf bir pozisyon veriyordu ama kodunuzu küçük yeniden kullanılabilir yöntemlere böldüğünüzde ve aşağıdaki gibi basit püf noktaları kullandığınızda tavsiyesine uydum:

• Tüm ifadeleri bir yöntem içinde aynı soyutlama seviyesinde tutmak
• Kontrol akış koşulunun veya döngü bloklarının içeriğini yöntem çağrılarına çekmek
• Kendinizi aynı parametreleri bir sınıftaki birkaç yönteme geçirirken bulduğunuzda yeni bir sınıf ayırarak
• Kriptik boolean ifadeleri yöntem çağrılarıyla değiştirmek gibi basit hileler
• vb...

Anlaşılması ve bakımı daha kolay olan okunaklı, biraz kendi kendine belgelendirme koduyla (özlü, ancak tanımlayıcı isimlere çaba gösterdiğiniz sürece) bitirdiniz.

Bunları gerçekten faydalı buldum, ancak iyi yapmak için bir tasarım kalıpları bilgisi gerektirir ve kesinlikle yaklaşımı sınıf ve üst düzey yöntem dokümantasyonu ile tamamlamanız gerekir.

Genellikle kendi kendini belgeleyen kod, kodun amacının kendiliğinden açık olması için değişkenler, işlevler vb. İçin adlandırma kurallarını kullanma uygulamasını ifade eder. Yani, hiçbir kod kendiliğinden belgelendirme değildir. Üçüncü paragrafta neyi kastettiğinizi anlamıyorum. Bu kendi kendini kodlayan kod ile ilgisi yok gibi görünüyor.

Jack Reeves, kodun tasarım olduğu konusunda zorlayıcı bir tartışma yaptı . Pek çok kişi söz konusu olduğunda, gerçek kod, sistemin ne yaptığını söyleyen tek "belge" dir. Her şey canlı bir sistem olarak bozuluyor, tasarlanan sistemden daha da uzaklaşıyor. Koddan bir belge oluşturacak olsanız bile (bugünlerde birçok UML aracı yapabildiği gibi), o zamanlar yalnızca sistemin o zamanki kesin bir belgelendirmesini sağlar .

Yani evet kod kendini belgeliyor. Ne kadar iyi belgelendirildiği tamamen başka bir sorudur.

Daha tecrübeli hale geldiğimde, asıl cevabın kodun artı okuyucunun ortamının kendi kendini belgeleme seviyesini belirlediği olduğunu öğrendim.

Okuyucunun ortamı ile yazarın çevresi arasındaki farkı en aza indirmek için yorumlar ekleriz. Ne kadar çok yorum gerekirse, yazar o kadar az deneyimli olur. Yazılım geliştirmenin bu yönünü açıklayan çok güzel bir makale var, fakat onu kimin yazdığını veya nerede bulduğumu hatırlamıyorum.

Çoğu insanın bu soruya beklediği cevabın "hayır" olacağını biliyorum ama evet diyeceğim. Bunu bir iş görüşmesine sorarsam, yine de evet derdim.

Açık ve kapalı kaynak kodlu birçok farklı projede çalıştım. Dokümantasyonda, programcının notları olarak bırakılan basit yorumlardan tam API dokümantasyonlarına kadar uzanıyorlardı. API dokümantasyonu harika olsa da, kodun fiili davranışını belirlemek için yazılı dil dokümantasyonunun yetersiz kaldığı bir duruma hep ulaştım. Kaynak koduna bakmaktan, uygulamaları tersine mühendislik yapmaktan veya kaynak koduna bakmak ve daha fazla belirtmek için geliştiricilere kaynak erişimi sağlamaktan vazgeçtim.

Bana göre, kod nihai belgelerdir. Bir programın ne yapacağını kelimelerle ne kadar yazarsanız yazınız, kesin davranış kodla tanımlanır.

Kod yazarken, kodunuzu mümkün olduğu kadar kendi kendinize tarif etmeye çalışmanız gerektiğini kabul ediyorum. Ancak diğerleri de belirttiği gibi, karmaşık bir programda, kodun yaptığı her şeyi tamamen açıklamak neredeyse imkansızdır. Yorumlara karşı değilim, aslında iyi yorumlarla kod okumayı kolaylaştıracağını düşünüyorum, ancak kod İngilizce veya bazı konuşma dillerini okuyan yorumlar olmadan kendini açıklayabilse de neredeyse her zaman daha kolay.

En kullanışlı belgelerin neredeyse hiç yorum olmadığını gördüm. Son zamanlarda üzerinde çalıştığım projelerin çoğunda, tüm farklı parçaları ve bağlantılarını içeren wiki de var. Kodu yazarken aklımda ne olduğunu açıklamaya çalışıyorum, böylece diğer insanlar kodumu kırmayacak çünkü nedenini anlamadılar. Ayrıca, başka birinin daha güvenli bir şekilde kodu yeniden düzenlemesine yardımcı olabilir. Kendimi çoğu zaman yeniden kodlama konusunda tereddütlü buluyorum çünkü ne kıracağını asla bilemiyorum ve hiçbir açıklama yok. Bir ya da iki yıl içinde bir proje üzerinde çalışan tek kişi olsanız bile, en güzel kod parçası olsa bile neden bir şey yaptığınızı unutacaksınız.

Tabii ki, eğer sınırsız zamanınız varsa. 25 + yıl boyunca diğer geliştiricilerin kodlarını belgeledim. Benim pozisyonum her zaman bir şeyi açıklamaya çalışmamdı, böylece başka bir geliştirici kodu 5 dakikada çözebiliyor, kodu basitçe inceleyip yarım saat içinde çözebiliyorlardı. Bu metoda bakan herkesi 25 dakika kurtarırsam, o zaman işimi yaptım.

Sınıf diyagramının her zaman kodu belgelemek için kullanılması gerektiğini düşünüyorum. Doğrudan koda bakarsanız tüm mimariyi göreceğinizi sanmıyorum. Eğer kodu kendiniz yazdıysanız veya üzerinde uzun süre çalışıyorsanız, anlayabileceğinizi kabul ediyorum ancak her seferinde yeni bir talep ortaya çıktığında, koda bakmanız ve bu yeni kodu nereye ekleyeceğinizi aramanız gerekir.

Şirketimizde yaptığımız şey, sınıf diyagramlarının projemizin görüşlerine sahip olmasıdır. Gerçekten zaman modellemesi yapmıyoruz, ancak tersine bir mühendislikten sonra kodu görüntülemek için sadece sınıf şemasını kullanıyoruz. Kod değişirse bir birleştirme mekanizması vardır ve sınıf diyagramlarım her zaman güncellenir.

Harika olan şey, java doc'ya ek olarak şemaya yorum ve kısıtlamalar ekleyebilmektir. Projeyi tersine çevirir, daha sonra bir model oluşturur ve son olarak UML sınıf şemaları olarak gösterilen modelden görünümler çıkarırız. Bu aşamada kod yazmıyorum ama kod mimarisinden mavi bir baskı alıyorum ve mevcut mimarimi oluşturmak veya genişletmek için üzerinde çalışıyorum. Eğer hoşuma giderse, bir düğmeye basarım ve mevcut kodum şemalarım ile birleşiyor. Birleştirme ve kesinlikle tam kod oluşturma demek istemiyorum. Yalnızca mevcut kod ile diyagramlarım arasındaki delta yazılır, her seferinde tam kod değil.

Uzun yıllardır çalışıyorum, yüksek lisans derecesine sahibim ve hala kod okuyorum ama sadece bir java yazarı olmak istemiyorum ve beynimi biraz daha kullanmak istiyorum. UML görünümleri, mimarlığım hakkında düşünmek, diğer takım üyeleriyle iletişim kurmak ve Model Driven geliştirmeyi kullanmadan daha iyi bir mimari oluşturmak için sadece ihtiyacım olanı veriyor; ancak yalnızca el ile yazılmış kod ile grafiksel olarak sınıf diyagramları oluştur. Mimarlığımı kod düzeyinde yaratıyorum, sonra tersine çeviriyorum ve modele bakıyorum. Görünümler oluşturuyorum ve mimaridimi doğrudan kodda geliştirmeye çalışıyorum, sonra tekrar tersine dönüp ne yapıldığını vb. Görüyorum. Model odaklı kod oluşturmayan kalıcı bir yineleme, ancak canlı senkronizasyon veya kod ile UML arasında birleştirme. Sevdiğim şey, kodun UML'yi kullandığı ve kesinlikle bunun tersi değil.