Kaynak kodu ve yazılım ürünlerini belgelemenin savunucusuyum. Benim kişisel deneyimim ve gözlemlerim, titizlikle yorumlanan kaynak kodları üzerinde çalışmanın, yazılımı büyütmek veya korumak zorunda kaldığımda bana farklı şekillerde yardımcı olduğu.
Ancak yorum yapmanın sonuçta değersiz olduğunu veya değerinin tartışmalı olduğunu söyleyen başka bir kamp var. Yorum yapmadan çok sayıda kodlama savunucusu:
- Bir kod parçası iyi yazılmışsa, kendi kendini açıklayıcıdır ve dolayısıyla yorum yapmaya gerek yoktur
- Bir kod parçası kendinden açıklayıcı değilse, yeniden düzenleyin ve herhangi bir yoruma ihtiyaç duymaması için kendi kendini açıklayıcı yapın
- Test paketiniz canlı belgelerinizdir
- Zamanla kod ve yorumlar senkronizasyondan çıkar ve başka bir baş ağrısı kaynağı haline gelir
- Agile, çalışma kodunun belge yığınlarından daha önemli olduğunu söyledi, bu yüzden yorum yazmayı güvenle yok sayabiliriz
Bana göre bu sadece dogma. Yine, kişisel gözlemlerim, akıllı ve deneyimli geliştiricilerden oluşan ekipler tarafından yazılan yazılımın sonunda kendini açıklayıcı olmayan önemli miktarda kodla sonuçlandığı olmuştur.
Yine, Java API, Cocoa API, Android API, vb. Kalite belgelerini yazmak ve bakımını yapmak istiyorsanız, bunun mümkün olduğunu göstermektedir.
Tüm bunları söyledikten sonra, belgelerin artıları ve eksileri hakkındaki görüşmeler ve kişisel inançlara dayanan kaynak koduna yorum yapmak genellikle iyi sonuçlanmaz ve tatmin edici sonuçlara yol açmaz.
Bu nedenle, yazılım dokümantasyonunun, özellikle kaynak kodunun yorumlanması, kalitesi ve sürdürülebilirliği üzerindeki etkilerinin yanı sıra ekip verimliliği üzerindeki etkileri hakkında akademik makaleler ve ampirik çalışmalar arıyorum.
Bu tür makaleler üzerine tökezlediniz mi ve bunların sonucu ne oldu?