Koddaki matematiksel mantığın belgelenmesi

Bazen, sık olmasa da, koduma matematik mantığı dahil etmek zorundayım. Kullanılan kavramlar çoğunlukla çok basittir, ancak sonuçta ortaya çıkan kod değildir - belirsiz amacı olan çok sayıda değişken ve çok açık olmayan bir amacı olan bazı işlemler. Ben bu sadece o kod okunamaz veya unmaintainable anlamına gelmez waaaay gerçek matematik problemi daha iyi anlamak zor. Anlaması en zor kısımları yorumlamaya çalışıyorum, ama sadece onları kodlamakla aynı sorun var - metin matematiğin ifade gücüne sahip değil .

Karmaşık kodların bazılarının arkasındaki mantığı, tercihen kodun kendisinde açıklamanın daha verimli ve kolay anlaşılır bir yolunu arıyorum. Ben TeX düşünmüştüm - belgeleri yazma ve koddan ayrı olarak oluşturma. Ama sonra TeX öğrenmek zorunda kalacaktım ve dokümantasyon kodun kendisinde olmayacak. Düşündüğüm bir başka şey de, kağıt / beyaz tahta üzerine yazılan matematiksel gösterimlerin, denklemlerin ve diyagramların resmini çekmek ve javadoc'a dahil etmek.

Daha basit ve daha açık bir yol var mı?

PS Değişkenlere açıklayıcı isimler vermek ( timeOfFirstEventyerine t1) kodu daha ayrıntılı ve daha da zor okunur hale getirir.

Bu gibi durumlarda yapılacak doğru şey, algoritma, formül veya birincil gerçek dünya kaynağındaki tam olarak aynı değişken adlarına sahip olan her şeyi uygulamaktır (programlama dilinin buna izin verdiği ölçüde) ve üstünde özlü bir yorum yapmaktır. "Knuth1968] 'de anlatıldığı gibi Levenshtein mesafe hesaplaması" gibi bir ifadeyle alıntı, matematiğin kolayca erişilebilir bir tanımına bağlanır.

(Eğer yoksa sahip böyle bir başvuru, ancak matematik belki kendiniz yayınlayarak düşünmelisiniz, ses ve yararlıdır. Sadece diyor ki.)

Böyle algoritmalar uygulamak zorunda kaldığımda, yaptığım birkaç şey var.

1. Mümkün olduğunca algoritmayı kendi yöntemine veya tercihen sınıfına göre izole edin. Mevcut projem Mathkarmaşık algoritmalar eklemek için kendi eşdeğer sınıfına sahip.

2. Algoritmanın, ortak kısaltmalar veya terime steno referansları da dahil olmak üzere, düzensiz olarak ne yapması gerektiğinin bir özetini sağlayın. Bunu yöntemin kendisinde yapıyorum, bu yüzden kodla yaşıyor.

3. Algoritmanın teknik / matematiksel terimlerin bir özetini sağlayın ve bildiğim harici referansları ekleyin. Yine, yöntemi kendisiyle yapıyorum, böylece alakalı kalma şansı daha yüksek. Düz metin bu durumda harika değildir, bu yüzden matematiksel terimi olabildiğince iyi göstereceğim ve yanında bir parantez içinde açıklayacağım. Örneğin, x^y (x raised to the power y)

4. Algoritmayı bileşenlere nasıl böldüğümü belgeleyin ve her değişkenin algoritmada neyi temsil ettiğini belirtin. Örneğin.t1 is time of first event

5. Algoritmayı kodlayın ve karmaşık parçaları yorumlayın. Esasen, algoritmanın içinde açık veya anlaşılır olmayan bir adım attığım her yere yorum ekleyeceğim. Özellikle belirgin olmayan kısayolları ve uygulama içinde alabileceğim neden iyi olduklarını yorumladığımdan eminim.

6. Algoritmanın çalışmasını doğrulayacak bazı birim testleri yazın.

Son olarak, gerçekten, gerçekten, gerçekten karmaşıksa, o zaman kendimi bu projede geçirdiğim zamanın geri kalanında bu koda sahip olduğum gerçeğine istifa ediyorum.

Başka birinin kodu anlaması için harici bir belgeye güvenmekten hoşlanmıyorum. Evet, bazen özellikle gizli ayrıntılara girerken gerekli olabilir. Ancak mümkün olduğunda, her şeyi kodun içinde tutmaya çalışıyorum, böylece güncellenmiş ve kolayca bulunma şansı var. Bu durumda, belgelerin anlamlılığı konusunda bilgiye erişilebilirliğe değer veriyorum.

Kantitatif finansal ekonomi araştırmaları etrafında dönen projelerimizde, bir sürü matematik kullanıyoruz ve zaten yayınlanmış olanların bir kombinasyonunu takip ediyoruz:

1. Kullandığınız ana kaynağa bir bağlantı sağlayın. Bizim için bunu yapmanın en kolay yolu, temelde ilgili herkesin arayabileceği bir makalenin kimliği olan BibTex sapını kullanmaktır. Spesifik kaynağa bağlı olarak, denklem referansını da düzenli olarak ekliyoruz.

2. Tüm değişkenler için açıklamalar sağlayın. Yine, orijinal kağıt Yunanca veya diğer harfleri kullanıyorsa bunun için Tex'i kullanırız. Bunun nedeni genellikle yeterli sayıda makale ve kitabın farklı gösterimler kullanmasıdır. Birinin matematik üzerinde yeniden çalışması gerekiyorsa, bu çok daha kolay hale getirir.

3. Denklemi tek parça olarak kodlamaya çalışın. Bu şekilde tanımak çok daha kolay. Tam denklemin Tex-Code'unu koda GÖNDERMEYİN - ya denklem çok kısadır ve tex göndermek dağınık ve gereksizdir veya denklem çok büyüktür ve siz derlemediğiniz sürece tex kodu işe yaramaz. referans). Bir denklemin küçük parçalara ayrılması, neler olup bittiğini anlamayı gerçekten zorlaştırır (en azından matematikte iyiyseniz).

IMHO, en önemli farkındalık, formüllerin genellikle bağlama bağlı olduğudur. Bildiğim her matematik makalesi, modelin ortamını oluşturmak için zaman alır; Aynısını yapmalısın.

metin, matematiğin ifade gücüne sahip değildir

Haklısın. Zaten kodun dışında yapmanın bir yolunu aradığınızdan ve Tex, dik bir öğrenme eğrisine sahip olmanın yanı sıra aşırı bir ölüm olduğundan, tavsiyem aşağıdaki gibidir:

OpenOffice.org/LibreOffice Matematik Denklem Düzenleyicisi'ni kullanın.

Bedava. Açık.

Görsel olarak kullanabilir veya denklemleri özel bir dilde yazabilirsiniz.

Dili hemen öğrenmek zorunda değilsiniz çünkü GUI'yi kullandığınızda, görmeniz için bir panelde "kod" oluşturulur.

Üst panelde denklemleri bir palet kullanarak "çizebilirsiniz". Alt panelde eşdeğer gösterim oluşturulur. Gösterimi kavradığınızda, alt panelde notasyon yazarak ve üst panelde grafik çıktısını gördüğünüzde bunu başka şekilde yapabilirsiniz.