Mutlaka karmaşık kod yapılarını nasıl belgeleyebilirim?

Matematiksel veya yapısal olarak oldukça karmaşık ve indirgenemez bir kod parçam varsa, bu kod parçasını belgelemeye nasıl devam edebilirim? Özellikle, yaptığım matematik veya mimari becerilere sahip olmayan birinin bunu belgelerden anlayabilmesini nasıl sağlayabilirim? Tüm matematiği de belgelemeli miyim? Bir öğreticiye bağlantı? Karmaşık yapılarda görsel yardım bağlantısı var mı?

Bu gerçekten kodun ve matematiğin ne kadar karmaşık olduğuna bağlıdır. Kodun kendisi - her zaman olduğu gibi - mümkün olduğunca kendi kendini belgelemelidir. Değişkenleri doğru bir şekilde adlandırın, mantıksal ve özlü yöntemler (mega işlevler yerine) uygulayın, uygun durumlarda satır içi belgeleri ekleyin (yani, kodun gerçekten ne yaptığını açık değilse).

Açık olmayan bir algoritma kullanıyorsanız, kaynağa bir referansa bir bağlantı ekleyin. Bu makul bir uygulamadır, çünkü geliştiriciye ne yaptığınızı öğrenmek için çok hızlı bir yol sağlar. Dediğim gibi, bu açık olmayan ama karmaşık bir algoritma ise yararlıdır. Bu, (a) mantıklı bir şey yaptığınızı ve (b) birisinin işe yaradığını gösterdiğini kanıtlamalıdır.

İyi bir örnek, bulanık metin eşleşmesi etrafında yaptığım bazı çalışmalardır. Algoritmalar üzerinde önemli araştırmalar yaptım ve 'Smith-Waterman algoritması' olarak bilinen şeyi uyguladım (aslında DNA dizileri için kullanılır, ancak genellikle 'eşleştirme' için geçerlidir). Bu yüzden sadece algoritmayı uygulamak yerine, çevrimiçi referanslar buldum ve bir veya iki bağlantı ekledim. Yukarıdaki gibi, bu, (a) algoritmamın yayınlanan algoritma ile eşleştiğini ve (b) algoritmanın incelendiğini ve işe yaradığını gösterir.

Ancak bu, kodun nasıl çalıştığını ve çeşitli sınıfların ne yapması gerektiğini açıklamak zorunda değildir. Bazı 'gerçek' dokümanları (sistem için bir geliştirici kılavuzu) yazmaya başladığınızda, ne yaptığınızı açıklamalı ve gelecekteki destek için yeterli bilgi sağlamalısınız. Kanımca bu belge teknik olarak agnostik bir kişi tarafından okunabilir olmalıdır; 'küçültülmesine' gerek yoktur, ancak jargonu dışlamalı ve varsayılan bilgiye dayanmamalıdır.

Yapmanız gereken ilk şey kaynağı çevreleyen yorumlar. Bu, doğrudan kodla belgelere doğrudan bir bağlantı olmasını sağlar. Dokümantasyon çok karmaşıksa, yorumlarda yalnızca bir özet göndermeyi ve ardından mimari / karmaşık algoritmanın daha eksiksiz bir açıklamasını içeren bazı harici dokümanlara bir bağlantı göndermeyi düşünün. Ancak, çok karmaşık değilse, tüm belgeleri tek bir yere dahil etmeyi düşünün. Bu, kodunuzun / belgelerinizin senkronize kalma olasılığını en üst düzeye çıkarır ve birlikte okunur.

Kodu, ekibinizin / şirketinizin ihtiyaç duyduğu ölçüde belgeleyin. Eğer bir jr. dev kodunu korumak için gerekli olacak, bazı matematik hakkında ayrıntılı olarak gitmek zorunda kalabilirsiniz. Bu bir yönetim kararıdır ve size gerekli zamanı vermeleri gerekir.

Kodu daha az geliştirici tarafından değiştirildiğini hesaba katacak kadar belgelemeniz gerektiğini düşünmüyorum. Bu bir endişe kaynağıysa, belgelemeniz için zaman tanıyın.

Onlar için web araması yapmak zorunda değilsiniz.