Kod nasıl belgelenir?
Zaten bir ipucunuz var: Java API'sinin nasıl belgelendiğine bakın.
Daha genel olarak, her proje için geçerli olan benzersiz kurallar yoktur. İş açısından kritik büyük ölçekli projeler üzerinde çalışırken, belgelerin, küçük ölçekli bir açık kaynak kütüphanesi için yazacağım belgeyle hiçbir ilgisi yok, ki bu da orta ölçekli kişisel projemin belgelenmesiyle hiçbir ilgisi yok. .
Neden birçok açık kaynaklı proje iyi belgelenmedi?
Çünkü çoğu açık kaynaklı proje, eğlenceli olduğu için bu projelere katkıda bulunan kişiler tarafından üretilmektedir. Çoğu programcı ve geliştirici, dokümantasyon yazmanın ücretsiz yapılacak kadar eğlenceli olmadığını düşünmektedir.
Neden birçok kapalı kaynaklı proje iyi belgelenmedi?
Çünkü (1) iyi belgeler yazmak ve (2) bakımını yapmak çok fazla paraya mal olur.
Anında maliyet (belgelerin yazılmasının maliyeti) paydaşlara açıkça görülebilir: ekibiniz projeyi belgelemek için önümüzdeki iki ayı harcamak isterse, ödenmesi gereken iki aylık maaş tutarıdır.
Uzun vadeli maliyet (belgelerin bakım maliyeti) yöneticiler için de oldukça kolaylaşır ve genellikle maliyeti düşürmeleri veya gecikmeleri kısaltmaları gereken ilk hedefdir. Bu, hızlı bir şekilde işe yaramaz hale gelen ve güncellenmesi oldukça pahalı olan ek bir eski belge sorununa neden olur.
Uzun vadeli tasarruflar (sadece birkaç yıl önce belgelenmesi gereken temel bir şeyi anlamak için eski kodu araştırmakla birkaç gün harcamak zorunda kalmamaktan kaynaklanan tasarruf), diğer taraftan, bazı yöneticilerin duygularını doğrulayan ölçülmesi zordur. dokümantasyon yazmanın ve sürdürmenin zaman kaybı olduğunu.
Sık sık gözlemlediğim şey şudur:
Başlangıçta, takım çok fazla belge vermeye isteklidir.
Zaman içinde, son tarih baskısı ve ilgisizlik, dokümantasyonu korumayı zorlaştırır.
Birkaç ay sonra, projeye katılan yeni bir kişi pratik olarak dokümantasyonu kullanamaz, çünkü gerçek sisteme hiç uymuyor.
Bunu farketmeksizin, yönetim, geliştiricileri dokümanları sürdürmediği için suçluyor; geliştiriciler birkaç hafta boyunca bunu güncellemek istiyorlar.
Yönetim bunun için birkaç hafta verirse, döngü tekrar eder.
Eğer yönetim önceki tecrübelere dayanarak reddederse, ürün dokümantasyondan yoksun olduğu için sadece kötü tecrübeyi arttırır, ancak birkaç ay yazıp sürdürmek için harcanmıştır.
Dokümantasyon, tıpkı test gibi, sürekli bir süreç olmalıdır. Birkaç hafta LOC'yi kodlamak ve testlere ve belgelere geri dönmek çok acı vericidir.
Ekibi dökümantasyona teşvik etmek nasıl teşvik edilir?
Benzer şekilde, insanları temiz kod yazmaya, düzenli yeniden düzenlemeye, tasarım modellerini kullanmaya veya yeterli birim testi eklemeye teşvik etmenin yollarına benzer.
Örnek olarak kurşun. İyi bir belge yazarsanız, çiftleriniz de bunu yapmaya başlayabilir.
Belgeleri incelemeyi hedefleyen resmi kod incelemeleri dahil sistematik kod incelemeleri yapın.
Takımın bazı üyeleri iyi dokümantasyona (ya da dokümantasyona) özellikle antipatik ise, daha iyi dokümantasyon yazmasını önleyen engellerin neler olduğunu anlamak için konuyu özel olarak konuşun. Zaman yetersizliğini suçlarlarsa, sorunların kaynağını görürsünüz.
Birkaç hafta veya ay boyunca belgelerin varlığını veya eksikliğini ölçülebilir hale getirin, ancak buna odaklanmayın. Örneğin, LOC'ye göre yorum satırı sayısını ölçebilirsiniz, ancak bunu kalıcı bir önlem yapmayın, aksi takdirde, geliştiriciler yalnızca düşük puanlardan kurtulmak için uzun ama anlamsız yorumlar yazmaya başlayacaktır.
Oyunlaştırmayı kullanın. Bu önceki nokta ile birlikte geliyor.
Pozitif / negatif takviye kullanın .
(Bkz . SJuan76'nın yorumu ) Yorumların eksikliğini hatalar olarak kabul edin. Örneğin, Visual Studio'da XML belgeleri oluşturmak için bir seçeneği işaretleyebilirsiniz. Ayrıca, tüm uyarıların hata olarak kabul edildiğini kontrol ederseniz, bir sınıfın tepesindeki yorumun veya bir yöntemin bulunmaması derlemeyi durduracaktır.
Önceki üç maddeye gelince, bu dikkatle kullanılmalıdır. Bir süredir özellikle zor bir başlangıç programcı ekibi ile kullandım ve StyleCop uyumlu yorumlarla bitti:
/// <summary>
/// Gets or sets the PrimaryHandling.
/// </summary>
public Workflow PrimaryHandling { get; set; }
Hangi, hm ..., özellikle yararlı değil.
Unutmayın: otomatikleştirilmiş hiçbir şey, programcılar sizinle uğraşmak istediğinde kötü yorumları belirlemenize yardımcı olamaz . Yalnızca kod incelemeleri ve diğer insan görevleri yardımcı olacaktır.
Asgari dokümantasyona ihtiyaç duyulduğunda veya gerekli olmadığında iyi örnekler var mı?
Mimariyi ve tasarımı açıklayan dokümantasyon gerekli değildir:
Bir prototip için
Bir görevin tamamlanması için birkaç saat içinde yazılan kişisel bir proje için, bu projenin artık sürdürülmeyeceğinden emin olarak,
Küçük olduğu göz önüne alındığında, özellikle temiz kodla birleştiğinde, belgeyi yazmak için gelecekteki tüm koruyuculardan daha fazla zaman harcamak için belge harcayacağınız açık olan herhangi bir proje için.
Bazı geliştiricilere göre, kod kendi kendine belgelendirilirken kod içi belgelere (kod yorumları) gerek yoktur. Onlar için, yorumların varlığı, nadir durumlar dışında, iyi bir işaret değil, yorumlara ihtiyaç duyulmaksızın kodun yeterince düzeltilmediğinin bir işaretidir.
Bir proje teslim edildikten sonra dokümantasyon incelemesi yapmamız gerektiğini düşünüyorum.
Projeniz haftada en az bir kez teslim edilirse, yol budur. Projeniz çevik değilse ve altı ay aralıklarla gerçekleştiriliyorsa, daha düzenli incelemeler yapın.