Ne kadar dokümantasyon yeterlidir?

Ne kadar teknik (gelecekteki geliştiriciler için) dokümantasyon yeterlidir ? Saat kodlaması ile saat dokümantasyonu arasında uygun bir oran var mı?

Papadimoulis yapman gerektiğini savunuyor

en iyi anlaşmayı kolaylaştırmak için gereken en az miktarda dokümanı hazırlamak,

Bu iyi bir kılavuz mu, yoksa oluşturmam gereken belirli şeyler var mı?

Koridorda kullanılabilirlik testine ne dersiniz? Kodu ve belgeleri, projeye aşina olmayan bir geliştiriciye gösterin. Kodu gözden geçirirken bir şeyi açıklamaya zorlama dürtüsü olmadan bunu yapabildiğinizde, yeterince var.

La perfection est atteinte non pas quand il n'y bir artı rien à ajouter, mais quand il n'y bir artı rien à emekli.
Antoine de Saint-Exupéry

Bir süredir bu konuyu düşünüyorum.

Sonuç olarak - bu bir nicelik meselesi değil, kalite ve bağlam meselesidir.

Örneğin, uygun bir proje yapısı dosyaların nerede bulunduğunu açıklayan yorumları yener (uygulama ve niyet)

Benzer şekilde, bağlamı açıklığa kavuşturmak için sınıflandırma adlandırma atıyor (Bir Hastada Id -> Hasta.Id).

DDD'nin iyi dokümantasyonda söz sahibi olduğuna inanıyorum - sınıflandırma bağlam sağlar, bağlam sınırlar oluşturur ve sınırlar kasıtlı uygulamalara yol açar (bunun olması gerektiğinden ziyade ait olduğu yer budur).

Kendi başına kod, dokümantasyon olarak kabul edilecek kadar iyi değildir. Çoğu durumda sorun, kodların çalışmasının yorumlandığı veya yorumlanmadığı gerçeğinde değil, itici güç (alan mantığı) değildir.

Bazen kimin patron olduğunu unuturuz - kod değişirse, etki alanı mantığı veya muhakemesi olmamalı, ancak etki alanı mantığı veya muhakemesi değiştiğinde kod kesinlikle değişecektir.

Tutarlılık da çok önemlidir - tutarlı değilse kendi başına konvansiyon işe yaramaz.

Tasarım kalıpları sadece 'iyi uygulama' değildir - geliştiricilerin anlaması gereken lingo. Bir geliştiriciye bir Fabrikaya yeni bir tür eklemesini söylemek, yönteme yeni bir tür eklemekten (bağlam ve tutarlılığın zayıf veya eksik olduğu) daha iyi anlaşılır.

Mücadelenin yarısı aşinalıktır .

Bir yan not olarak, çok sayıda belgeyi tercih eden API'ler de alan adına ve içeriğe duyarlıdır. Bazen çoğaltma işlevselliği kötü değildir (aynı şey, farklı bağlamlar) ve ayrı olarak ele alınmalıdır.

Yorum yapmak açısından, mantığın ardındaki alan mantığını belirtmek her zaman iyidir.

Örneğin, tıp endüstrisinde çalışıyorsunuz. Yönteminizde "IsPatientSecure = true;"

Şimdi, iyi bir programcı hastanın güvenli olarak işaretlendiğini anlayabilir. Ama neden? Etkileri nelerdir?

Bu durumda hasta, tesis dışı bir hastaneye güvenli bir şekilde nakledilen bir mahkumdur. Bunu bilerek, bu noktaya giden olayları (ve belki de hala olması gerekenleri) hayal etmek daha kolaydır.

Belki de bu yazı en iyi ihtimalle felsefi görünüyor - ama yazdığınızın 'mantık' ya da 'mantık' olduğunu unutmayın - kod değil.

Papadimouslis sözüne katılıyorum. Kaynak kod kendisi için konuşabilir, ancak kod size neden var olduğunu, nasıl kullanılması gerektiğini ve kodun nasıl davranması gerektiğini söyleyemez.

İyi bir oran bilmiyorum.

Çok az dokümantasyonla yüzlerce kod satırını miras aldım. Kodun neden yazıldığını anlamak benim için zor oldu. Kodun neden yazıldığını öğrendikten sonra, kodu nasıl kullanacağımı bulmak zorunda kaldım. Bunu öğrendikten sonra, kodu destekleyip koruyabilmem için nasıl davranması gerektiğini düşünmek zorunda kaldım.

Sadece deneyime göre, yorumları çok özel yapmayın, aksi takdirde gerçek kodu VE belgeleri korumak zorunda kalacaksınız. Belgelerin ve kodun senkronize olmadığı bir kabus.

Kendinizi tahmin etmeyi bırakmanız için yeterli.

Çalışmanız sırasında herhangi bir zamanda "hmm belki bunu belgelemeliyim" gibi biriyseniz, devam edin ve yapın. Sonra, bazı belgeler yazdıysanız ve "belki bunu daha fazla açıklamalıyım" gibiyseniz, devam edin ve yapın.

Bu his kaybolana kadar durulayın .

George Fairbanks'ın Just Enough Software Architecture kitabında sunulan gibi risk odaklı bir yaklaşımın, ne kadar belgenin yeterli olduğunu anlamak için son derece iyi çalıştığını buldum . Bu kavramı (bölüm 3) sunan bölümü web sitesinde okuyabilirsiniz, ancak ana fikir:

• "Sistem anlayışı" konusunda endişe duyduğunuz şeyleri risk olarak ifade edin
• Risklere öncelik verin
• Ekibiniz proje riskinin yeterince azaldığını hissedene kadar riskleri azaltın. Bu durumda, muhtemelen bir tür belge oluşturacaksınız.

Riskleri önceliklendirebilmeniz için endişelerinizi kalibre etmeye yardımcı olmak amacıyla , Başarı Eşiği olarak bilinen birkaç hedefin tanımlanmasını yararlı buldum . Dokümantasyon perspektifinden bakıldığında, ToS örneği "Bir geliştirici çerçeveyi ilk kez aldıktan sonra 4 saat içinde basit bir eklenti oluşturabilmelidir" gibi bir şey olabilir.

Şimdi bazı riskleri belirleyin. Oluşturduğunuz (veya inşa ettiğiniz) sistemde ekibinizi en çok endişelendiren şeyler nelerdir? Bunları risk ifadeleri olarak ifade edin. SEI'nin durum-sonuç stilini seviyorum ama başkaları da var. Örnekler:

• Veri modeli büyük ve karmaşıktır; geliştiriciler, belirli bir durumda hangi veri öğelerinin kullanılacağını bilemeyebilir.
• Sistemin güvenilirliği artırmak için API bağlantı sınırları vardır; geliştiriciler bağlantı sınırını yanlışlıkla aşabilir.
• Eklentiler birkaç ardışık adımda tüketilir; geliştiriciler bu sıralı adımları göz önünde bulundurarak eklentiler oluşturamayabilir.

Şimdi ekip olarak risklere öncelik verin. Çoklu oylama son derece iyi çalışıyor.

En yüksek öncelikli riskleri azaltın ve projenizin başarısız olma riski (Başarı Eşiği tarafından tanımlanan) kabul edilebilir bir sınır dahilinde oluncaya kadar kimlik tespiti ile başlamayı tekrarlayın. Genel olarak bu, takımın endişe duymadığı konusunda bazı riskleriniz olacağı anlamına gelir. Muhtemelen tüm riskleri azaltmak istemeyeceğinizi unutmayın. Yukarıdaki son risk için bir azaltma stratejisi örneği bir öğretici oluşturmak olabilir.

Mümkün olduğunca az, ancak gerektiği kadar

Bunu ilk nerede ve ne zaman duyduğumu hatırlayamıyorum, ancak birçok uygulama ile bir maksimum.

Teknoloji ya da uygulama ne kadar karmaşıksa, o kadar çok dokümantasyona ihtiyaç duyulacaktır (açıkçası), ancak açıkça denize girmek için zaman kaybetmek istemezsiniz.

JohnFx'in 'koridor testi' sağlam. Ama kendine güven; kodu geliştirdiniz ve bu yüzden tüm insanların sizden daha fazla dikkat edilmesi gereken unsurlar ve herkes için açık olacak unsurlar hakkında fikir sahibi olması gerekir. Kodu geliştirdiğiniz mücadeleleri düşünün ve muhtemelen başka bir geliştiricinin kodunuza baktıklarında ne görecekleri hakkında bir fikriniz olacaktır.

Kodlama için harcanan çaba ile belgeleme için harcanan çaba arasındaki ilişkiyi unutun.

Bunu kesin kurallara koyamayacağınıza inanıyorum. Belgelemenin nedeni, ham koddan kolayca toplanmayan bilgileri bir formda sağlamaktır, böylece diğerleri söz konusu ham kodu anlayabilir ve hatta koruyabilir.

Bu nedenle, yeterince belgelendirip belgelemediğinizi anlamanın tek yolu, hedef kitleye yeterince iyi olup olmadığını sormaktır. "Akran inceleme" sürecinin bu ön yapıyor çok iyi olduğuna inanıyorum. Akranınızın ne hakkında konuştuğunuzu anlamasını sağlamak için ne kadar açıklamanın gerekli olduğuna dikkat edin ve bunu en aza indirmek için çalışın.

Bunu daha önce hiç yapmadıysanız, ne kadar iş alacağını tahmin edemezsiniz, ancak birkaç iterasyondan sonra ne kadar ihtiyaç duyulduğuna dair daha iyi bir fikir elde edersiniz.