Mevcut kod tabanını belgelemek için metodoloji

Satır içi dokümantasyonu olmayan mevcut bir uygulama üzerinde ekibin bir parçası olarak çalışıyorum ve teknik dokümantasyonu da yok. Uygulamadaki çeşitli hata raporları üzerinde çalıştığım için, kendim için bir çeşit ekmek kırıntısı izi yazdım - çeşitli yerlerdeki hata numaraları. Böylece bir sonraki geliştirici neler olduğunu görmek için bu hata numarasına başvurabilir.

Sorum şu:

Bu kodu belgelemek için en etkili yöntem nedir? Bölgeye dokunduğumda (virüs yöntemi, eğer istersen) belgelenmeli mi, yoksa her bölümden kendi başına belgelemeli mi ve uygulamanın diğer alanlarına yayılan yolları izlememeli miyim? Daha önce bulunmayan yerlere satır içi yorumlar eklemem gerekir mi (kodun ne yaptığını saptamayacağımı söyleme korkumla)?

Var olan satır içi belgelere sahip olmayan oldukça büyük bir uygulamayı veya dış belgelere satır içi referansları doğru ve hızlı bir şekilde belgelemek için hangi yöntemi kullanırsınız?

Eski kod tabanlarını belgelemek

Eski kod temelli izci kurallarını izlemenizi şiddetle tavsiye ederim . Eski bir projeyi üzerinde çalışmaktan bağımsız olarak belgelemeye çalışmak asla gerçekleşmeyecek.

Kod içi belgeler

En önemli şey, seçtiğiniz geliştirme ortamındaki dokümantasyon olanaklarını kullanmaktır, bu nedenle python için pydoc , java'da javadoc veya C #'daki xml yorumları anlamına gelir . Bunlar, dokümantasyonu kod yazmakla aynı anda yazmayı kolaylaştırır.

Daha sonra geri gelip belgelendirmeye güveniyorsanız, bunu çözemeyebilirsiniz, ancak kodu yazarken bunu yaparsanız, belgelenmesi gereken şey aklınızda taze olacaktır. C #, XML belgeleri eksikse veya gerçek kodla tutarsızsa derleme uyarısı verme seçeneğine de sahiptir.

Dokümantasyon olarak testler

Bir diğer önemli husus, iyi entegrasyon ve birim testlerine sahip olmaktır.

Çoğu zaman dokümantasyon, hangi sınıfların ve metotların izole edildiğine odaklanır ve probleminizi çözmek için nasıl bir arada kullanıldıklarını gösterir. Testler genellikle birbirleriyle nasıl etkileşime girdiklerini göstererek bunları bağlam içine koyar.

Benzer şekilde, birim testleri çoğu zaman açıkça işlerin üstesinden gelinmesi gereken dış bağımlılıkları işaret eder .

Ayrıca Test odaklı geliştirme kullanarak kullanımı daha kolay olan bir yazılım yazdığımı da biliyorum çünkü kullandığımdan beri kullanıyorum. İyi bir test çerçevesiyle, kodu test etmek daha kolay ve kullanımı kolay hale getirmek genellikle aynı şeydir.

Daha yüksek seviye dokümantasyon

Son olarak, sistem seviyesi ve mimari dökümantasyon hakkında yapılması gerekenler var. Pek çok kişi bu tür belgeleri bir wikide yazmayı veya Word veya başka bir kelime işlemcisini kullanmayı savunur, ancak benim için bu belgeler için en iyi yer, sürüm kontrol sistemi dostu olan düz bir metin biçiminde de kodun yanındadır.

Kod içi belgelerdeki gibi, üst düzey belgelerinizi de kod deponuzda saklarsanız, güncel tutmanız daha olasıdır. Ayrıca, kodun XY sürümünü çıkardığınızda, belgelerin XY sürümünü de elde edersiniz. Buna ek olarak, eğer bir VCS dostu format kullanıyorsanız, kodunuz gibi dallanması, dağılması ve birleştirilmesinin kolay olduğu anlamına gelir.

Oldukça gibi ilk , o ondan hem html sayfalarını ve pdf belgesi göstermek kolaydır ve çok daha dostça olduğu gibi LaTeX , henüz can hala şunlardır LaTeX matematik ifadeleri gereksinim duyduğunuzda.

Zor bir soru. Temel olarak, "koda dokunursanız, belgeleyin" olarak yeniden adlandırdığım "yeniden düzenleme" yöntemini kullanırdım.

Ancak kesin olmak gerekirse; sorunlar ortaya çıktıkça ve ortaya çıkan hataları düzeltmek için kodla aşina olmanız gerektiğine göre, bu aşinalık özellikle o kodla ilgili yorum yazmak için kullanmanız gerektiğini söyleyebilirim; özünde, hatayı gidermeye yönelik motivasyon bu noktada sizi belgelendirmek için kodla yeterince aşina olmanızı sağlamıştır. Ve bu nedenle, ilgisiz dalları takip etmeye ya da ilgisiz işlevleri belgelemeye istekli olacağım, çünkü bu noktada, kodun aktif testini yapmıyorsanız (hata düzeltmenizi doğrulamak için), o zaman tamamen zor kodun ne yaptığını ve nedenini tam olarak anladığınızdan emin olun. (Ben bir hata düzeltmeyi test ederken bile kodun ne yaptığını ve neden ve tam olarak ne olduğunu tam olarak çözmenin zor olacağı sorununa girmiyorum;

Bu yaklaşım, genel hızdan fedakarlık yaparak doğruluğu en üst düzeye çıkarma eğiliminde olmalıdır, ancak kodu aynı anda çok ciddi bir şekilde muhafaza etme ihtiyacınızı etkilememelidir. Hata düzeltme görevleriniz küçükse, elbette "bilinmeyen bölge" ye girebilir ve orada belgelendirmeye başlayabilirsiniz, ancak (çoğumuz gibi) gün içinde hem kodu düzeltip hem de belgelemek için yeterli zaman bulamazsanız, bu iyi bir uzlaşmadır.

Bir şey de dikkat çekiyor; iyi bir dış belgelere sahip olmalısınız. Kodunuzun dış belgelere referansları olmadığını söylüyorsunuz; Sizin iyiliğiniz için böyle bir dış belgenin var olduğunu umuyorum. Olmazsa, aslında bu dış belgeleri yazmaya öncelik verirdim; İşlevsel özellik düzeyinde bir şey olduğunu düşünüyorum, tüm büyük yazılım projeleri için kesinlikle kritik öneme sahip. Bunun nedeni, işlevsel özelliklerin veya bu formun üst düzey dokümantasyonunun herhangi bir yazılımda "özellik sünme" veya "özellik kayması" nın önlenmesine yardımcı olabileceğidir; ve özellik kayması (özellikle) belgelerin modası geçmiş olmasına neden olabileceği için belgelere zarar verebilir. (Özellik kaymasını , bir yazılım parçasına özelliklerin aşamalı (ve sinir bozucu) eklenmesi olarak tanımlarım; özellik kaymasıÖte yandan, yazılımın gerçekleştirdiği eylemler kümesinin zaman içinde yavaşça değiştiği yerdir. Özellik sürünmesi KATKI, yani genellikle yazılımın işlevsellik kümesinin arttırılmasını içerir; Öte yandan, özellik kayması sıfır toplamdır; birer birer uç işlevsellik, yazılım başlangıçta amaçlandığından tamamen farklı bir şey yapana kadar farklı bir şey yapmak için tanımlanır. Özellik kayması nadirdir, ancak dokümantasyon için HAZIR.)

İki yıl boyunca birlikte geliştirdiğim bir uygulamada ciddi bir dokümantasyon eksikliği vardı. Bir noktada, başvuruyu bu noktadan itibaren sürdürecek başka bir geliştiriciye devredeceğimiz anlaşıldı, bu yüzden kodu belgelemek zorunda kaldık.

Belgelendirme sürecinin devasa kapsamını ele almak için, kodun tamamını belirli bir günde veya uygulamanın bir bölümünde belirli bir günde dener ve belgelerim. Özel bir düzenim yoktu, ancak her gün bazılarını yapmakta ısrarlıyım ve günlük olarak uygulamanın bütün bir bölümünü veya bir bölümünü belgeleyerek tamamlanma duygusu alıyorum.

Tüm başvuruyu belgelemek aylar aldı, ancak günde yarım saatte (en fazla) hiçbir zaman proje programına dahil olmadı ve belgeleme ile birlikte gelen çok fazla todyumdan kaçındı.

XML belgelerini C # dilinde kullandık ve belgelendirmeyi kolaylaştırmak için yeterli özellikleri ve yapıları sağladık. Bir C # uygulamasını belgelemeseniz bile, önce kısa bir özete sahip olmanın ve ardından açıklamaların deseni çok işe yaramazdı.

Kod eklediğim / değiştirdiğim gibi belgeliyorum. Bunun dışında ortak API'leri veya modüller arasındaki tüm arayüzleri de belgeleyeceğim. Kodun tamamını belgelemeniz durumunda, harcanan süre için YG'yi göremeyebilirsiniz. Dış belgeleri düzenlemek için wiki gibi bir şey kullanmak, onu geliştirirken yararlı olabilir. Son projeme başladığımda başvurduğum en yararlı belge mimarlık dokümanıydı. Kullanılan teknolojiler hakkında bilgi içermekte ve uygulamanın nasıl katmanlaştırıldığına ilişkin üst düzeyde bir görüş sunmuştur.

Doxygen yorumlarını kullanırdım. Doxygen, diğer çoğu serbest formattan daha fazla çıktı formatına sahiptir ve öğrenmesi kolaydır.

Bunu yapmak için bir müteahhit kiralamayı düşünebilirsiniz, çünkü bazılarımız geçimini sağlamak için. Ancak, bu seçimde, hala belgeleri incelemeyi taahhüt etmeniz gerekir.

Yaygın olarak kullanılan başka bir teknik de yeni devi kodu belgelemeye atamaktır. O zaman her yeni insanın hız kazandıkça geçmesini sağlayın. Bazı geliştiricilerin buna bir kök kanalı sağladığının farkında olun - yalnızca doğrudan durumlarda LOL gereklidir.

Herhangi bir şeyi belgelendirmeye başlamadan önce bir standart geliştirin. Bu, bir fonksiyon veya sınıf başlığının üstündeki birkaç satırı daha resmi ve ayrıntılı bir şeye (javadoc gibi) yazdığınızdan emin olmak kadar basit olabilir. Herhangi biri kodu kontrol etmeden önce, belgelerinin bu standarda uyması gerekir.

İyi çalıştığım şey, daha önce belgelenmemiş işlevler için işlev başlığından önce iyi yazılmış yorumlar eklemek ve eklediğim herhangi bir şeye satır içi yorum eklemek. Dokunmadığınız kodları belgelemek istemezsiniz. Yorum yapmamaktan ziyade kötü yorumlara sahip olmak daha kötü bir şeydir ve eğer bunu 'hızlı' bir şekilde belgeliyorsanız, muhtemelen kötü yorumlar yazacaksınız.