Kod dökümantasyonu verimlilik kazançları / kayıpları üzerine çalışmalar

Çok fazla arama yaptıktan sonra, yazılım geliştirme dünyasında bilinen bir varsayımla ilgili temel bir soruya cevap veremedim:

NE BİLİNİYOR:

Yeterli kod dokümantasyonu (Doxygen etiketleri, Javadoc ya da sadece çok sayıda yorum olsun) konusunda katı bir politika uygulamak, kod geliştirmek için gereken süreye ek yük getirir.

FAKAT:

Kapsamlı belgelere (hatta bir API'ya) sahip olmak, yeni ve deneyimli geliştiricilerde özellikler eklerken veya hataları yolda sabitlerken verimlilik kazançlarını (bir varsayım) beraberinde getirir.

SORU:

Bu tür belgelerin yoldaki üretkenlikteki kazançlarla (kesinlikle ekonomik anlamda) dengelenmesi için gereken ilave geliştirme süresi var mı?

Vaka çalışmalarını veya beraberinde getirilen sonuçları destekleyen nesnel kanıtları getirebilecek cevaplar arıyorum.

Şimdiden teşekkürler!

"Tipografik stil kozmetikten daha fazlasıdır" makalesi oldukça eskidir ama çok ilginçtir: http://portal.acm.org/citation.cfm?id=78611 .

Eski olmak, bugünlerde mümkün olacağını tüm süslü şeyler içermez fakat kod belgeleri açıkça gösteriyor yapar olsun.

Benim gibi ACM dijital kütüphanesine erişimi olmayanlar için iki grup programcı oluşturdular ve çalışmalarına aynı kodu verdiler. A grubu sadece normal yorumlarla kodu aldı, B grubu içindekiler tablosu, çapraz referans ve 1990'da mümkün olan tüm incelikler ile oldukça basılı bir liste aldı.

Daha sonra iki gruptan kod üzerinde belirli görevleri yerine getirmelerini istediler (örn. Bir işlevi genişletme, bir hata bulma, ...) ve cevapların hızı ve kalitesi açısından puanlama yaptılar.

Grubu dengelemek için aynı sayıda uzman ve genç programcı vardı.

Pekala, B grubunun (güzel yazdırılmış listeye sahip olan) çok sayıda testte A grubundan daha iyi puan aldığını ortaya çıkardı. Ve belirli durumlarda, sadece A grubunun en uzmanları B grubunun genç programcısını geçmeyi başardı.

Makale daha fazlasını söylüyor ama bellekten hatırlayabildiğim şey bu (basılı makaleyi hala bir yerde bulundurmalıyım).

En azından benim için, okunabilir kodun sadece kötü yazılmış kodları telafi etmeye yarayan dokümantasyondan çok daha değerli olduğu açıktır . Ben kodu yeniden yazma ve daha kendi kendine açıklayan yapmak yorum kaldırmak olup olmadığını görmek için kodda yorumları bir meydan okuma olarak düşünmek eğilimindedir.

Bunu sağduyunun dışında sert bir kanıtla destekleyemem.

Alıntı yapmak için herhangi bir çalışmam yok, ancak basit bir kuralım var: İki hafta sonra koduma geri dönersem ve ne yaptığımı hemen anlayamazsam, daha fazla yoruma ihtiyaç duyar veya basitleştirilmesi gerekir .

Elbette, kodunuzun nasıl çalıştığı kodun kendisi tarafından belgelenmelidir. Ancak zaman , kodu koruyan tek kişi siz olsanız bile, kodunuzun neden yazıldığına dair kesinlikle yazdığı şekilde yazıldığını dikkatle ve kısa bir şekilde açıklayan yorumlar yazmak için harcanmıştır .

Bir yazılımın ömrü çoğunlukla bakım aşamasında harcanacaktır, bu yüzden programın ne olduğunu anlamanızdan sonra size yardımcı olan her şey neredeyse kesinlikle mali getiriler sağlayacaktır, çünkü geliştiricinin daha hızlı hızlanmasına yardımcı olur.

Biraz önemsiz olan herhangi bir API'de, koddaki API'yi belgelemek neredeyse işe yaramaz. Bunun nedeni, API'deki gücün bir bütün olarak birlikte nasıl çalıştığıdır (tek tek yöntemlerin / nesnelerin nasıl çalıştığı değil).

Bu nedenle, gerçek dokümantasyondan daha yararlı olan, API'nın beklenen kullanım modellerini ve API'nin çoğunluğunu (% 100 değil) kullanan bazı açık durumların nasıl çözüleceğine ilişkin örnekleri açıklayan yemek kitabı benzeri bir belgedir.

Belirli bir yöntemin, henüz icat edilmemiş araçlar olmadan, bu belgelerin yazılmasını gerektirecek kadar öznel olup olmadığına karar vermek .

"Tüm herkese açık yöntemler" veya belirli bir paketteki tüm sınıflar vb. Gibi en iyi tahmin uygulamaları yardımcı olabilir, ancak belirli kullanım durumlarının ötesinde önermek için çok kaba olabilir.

Benim önerim: Geliştiricilerinize iyi uygulamaları, belgelendirmek için önemli olan yöntemleri (resmi veya gayri resmi API, yaygın olarak kullanılan saplama yöntemleri, karmaşık veya ezoterik) nasıl belirleyeceklerini öğretin ve kendilerini yönetmelerine izin verin.

(Yakından ilgili: Kodlama standartlarında çok fazla tekdüzelik olabilir mi? )

^{Alıntı yapmak için herhangi bir çalışmam olmadığından özür dilerim, ancak bunun, herhangi bir ölçüm girişiminin sonucu genel sonuçları çıkarmak için çok fazla etkileyeceği bir sorun olduğundan şüpheleniyorum.}

Bence bu bağlamda "normal" kodu herkese açık API'lardan ayırmamız gerekiyor. Düzenli kod için, bu koddaki diğer cevaplayıcıların çoğunun kendi kendini belgelemesi ve neredeyse nesir gibi okunması gerekir . Kodum böyle değilse, genellikle benim hatamdır, bu yüzden belgelemek yerine yeniden düzenlenmesi gerekir. Bir seferde sadece bir şey yapan, tek bir soyutlama düzeyinde çalışan, doğru ve açıklayıcı bir ada sahip küçük yöntemler, bunu başarmak için harika bir yol olabilir.

Yorumlar ile ilgili sorun çürük olmasıdır. Bir yorum ekler eklemez, eşlik ettiği koddan bağımsız bir hayat yaşamaya başlar. Kodu değiştiren bir sonraki geliştiricinin ilgili yorumları da güncel bir şekilde güncelleme şansı nedir? Deneyimlerime göre, sıfıra yakın. Birkaç değişiklikten sonra elde edilen sonuç, yorumun insanlara yardım etmek yerine onları şaşırtması veya yanlış yönlendirmesidir.

Olası istisnalar, performansı optimize edilmiş kod veya belirli bir algoritma kullanmaktır . Bu durumda, kodun neden böyle göründüğünü, algoritmaya bir referans vb. Tanımlamak için yorumlar eklemek yararlıdır.

Bu konudaki seminal çalışma Temiz Kod'dur .

Herkese açık bir API olan OTOH , Javadoc'ta da gerçekten iyi belgelenmelidir . Çok çeşitli becerilere ve varsayımlara sahip sayısız toplam yabancı tarafından kullanılabileceğinden, mümkün olduğunca basit ve anlaşılır hale getirmek için herhangi bir önlem alınması gerekir. Bu hala büyük ölçüde uygun bir API tasarımı meselesidir, ancak dokümantasyon için de önemli bir rol vardır.

Sorun, kodunuzu belgelendirerek her bir geliştiricinin ne yaptığını anlamaya çalışmak zorunda bırakarak zaman kazanıp kazanmamanızdır. Kodunuz kod incelemesi yoluyla, kimse ne yaptığı hakkında herhangi bir soru sormadan uçarsa, muhtemelen iyi durumdasınız demektir. Girdiler hakkında yaptığınız varsayımları açıklamak çok zor değil. Diyelim ki yönteminiz bir tam sayı nesnesi alıyor ve bir dize nesnesi döndürüyor. İnt boş olabilir mi? Bir min / maks değeri var mı (integer.MinValue / MaxValue dışında)? Boş bir dize veya boş döndürebilir mi? Herhangi bir istisna atıyor mu? Elbette herkes bunları muayene ile bulabilir, ancak yeterli sayıda diğer geliştiriciler kodunuzu kullanacaksa, her birkaç dakikayı kaydetmek zaman ayırmaya değer. Ayrıca, test kullanıcılarına kodunuzu onaylamak için testler oluşturma konusunda bir adım atar.

Bu kesinlikle ilginç bir konudur, çünkü geliştiricinin belgeleri oluşturmak veya korumak için zaman harcaması gerekip gerekmediğine dair tartışmalar olmuştur, ancak gerçekte kod geliştiricinin kodu tekrar ziyaret ettiğinde bu şekilde iyi yazılmış ve çok iyi yorumlanmış olmalıdır. kodun nasıl yazıldığını ve ilk etapta ne yapması gerektiğini düşünmek için zaman harcamak zorunda kalmaz, ayrıca yeni ekip üyesi ekibe katılırsa, açıkça belgelendiği gibi kodun işlevselliğini ve çalışmasını anlayabilir.

Bu yüzden kod çok iyi yorumlanmalı ve bu nedenle herhangi bir harici belge gerektirmeyen kendi kendine belgelenmiş kod olmalıdır.

Kariyerimde, farklı düzeylerde belge ve kalite içeren kodlar gördüm (belge ve kalitenin ortoganal kaygılar olduğuna dikkat edin). Belgelere harcanan sürenin kaliteyi artırmak için kullanılmasını tercih ederim. Basit vaka için GhostDoc gibi bir işleve bakıp sizin için doktor yorumları oluşturabilen araçlar vardır. GhostDoc, işlevinizin ne yaptığını söyleyen anlamlı bir yorum oluşturabilirse, açıkça iyi adlandırılmış işlevlere sahip olma hedefine ulaşmışsınızdır.

Birçok durumda, GhostDoc size bir işlevin gerçekten ne yaptığını söylemeye bile başlayamaz. Bu sorunu ele almak ve kodunuzu otomatik olarak oluşturmak için ghostdoc'u kullanmak için zamanınız daha iyi harcanır.

Daha ayrıntılı bir tartışma için Bob Martin'den Kod ve PPP'yi temizleme bölümüne bakınız .