Bilimsel yazılımı belgelemek için iyi yollar nelerdir?

Çoğu zaman, başkaları tarafından yazılmış (ya da zaman zaman kendi çalışmam bile olsa) yazılmış bilimsel kodları miras aldığımda ya da karşılaştığımda, belgelerin ya seyrek ya da varolmadığını fark ettim. Şanslıysam bilgilendirici yorumlar görüyorum. Çok şanslıysam, Doxygen yorumları ve Doxyfile bile var, böylece işlev arayüzleri ve danışılacak bazı HTML kodları var. Çok şanslıysam, Doxygen ve kaynak dosya yorumlarına ek olarak bir PDF kılavuzu ve örnekleri de var ve çok mutluyum çünkü hayatımı çok daha kolaylaştırıyor.

Kaynak kodun belgelenmesinde hangi bilgiler ve araçlar faydalıdır? Bu konuda, bilimsel yazılım söz konusu olduğunda, bu kaynak koduna eşlik eden veri ve sonuçları belgelemek için hangi bilgi ve araçlar yararlıdır?

Bilimsel yazılım için dokümantasyonun, tam anlamıyla anlaşılması için gerekli olan üç kategoriye ayrılabileceğini düşünüyorum. En kolay ve en yaygın bireysel yöntem belgeleridir. Bunun için birçok sistem var. Sen söz doxygen Python vardır pydoc ve PETSc içinde biz kendi paket var ekim üretir aşağıdakileri .

Ancak, basit bir yardımcı programın ötesine geçen herhangi bir yazılım için bir kılavuza ihtiyacınız vardır. Bu, paketin amacına ve farklı işlevselliklerinin bu amaca ulaşmak için nasıl bütünleştiğine dair üst düzey bir görünüm sağlar. Yeni bir kullanıcının kodunu, genellikle örneklerin kullanımıyla yapılandırmasına yardımcı olur. PETSc'de sadece kılavuz için LaTeX kullanıyoruz, ancak PyClaw paketi çok etkilendiğim Sfenks çerçevesini kullanıyor . Ekim paketinde çok faydalı bulduğum bir şey, örnek kod ile fonksiyon dokümantasyonu arasındaki bağlantı. Örneğin, bu örnekBratu denklemini çözer. Herhangi bir özel tür veya işlev çağrısı için bağlantıları nasıl takip edebileceğinizi ve düşük düzeydeki belgelere nasıl ulaşabileceğinizi ve bu sayfaların bunları kullanarak örneklere nasıl geri döndüğünü görün. Bu, projedeki diğer insanların katkıda bulundukları yeni işlevsellik hakkında bilgi edinmemdir.

Belgelerin sıkça gözden kaçan bir kısmı bence geliştirici belgeleridir. Kodlama stili bir belge ve depo ile etkileşim için talimatlar yayınlamak nadir değildir. Ancak, uygulamadan önce verilen tasarım kararlarını açıklamak çok nadirdir. Bu kararlar her zaman travmalar içerir ve donanım ve algoritmalarla ilgili durum zaman içinde mutlaka değişecektir. Gözden geçirilen değişimler ve belirli tasarım kararları için gerekçelerin tartışılması olmadan, daha sonra programcılar tüm süreci kendi başlarına yeniden oluşturmak için ayrılırlar. Bunun, orijinal geliştiriciler artık sorumlu olmadığında, eski kodların başarılı bir şekilde sürdürülmesine ve iyileştirilmesine büyük bir engel olduğunu düşünüyorum.

Kod içi belgeler

En önemli şey, seçtiğiniz geliştirme ortamındaki dokümantasyon olanaklarını kullanmaktır, bu nedenle python için pydoc , java'da javadoc veya C #'daki xml yorumları anlamına gelir . Bunlar, dokümantasyonu kod yazmakla aynı anda yazmayı kolaylaştırır.

Daha sonra geri gelip belgelendirmeye güveniyorsanız, bunu çözemeyebilirsiniz, ancak kodu yazarken bunu yaparsanız, belgelenmesi gereken şey aklınızda taze olacaktır. C #, XML belgeleri eksikse veya gerçek kodla tutarsızsa derleme uyarısı verme seçeneğine de sahiptir.

Dokümantasyon olarak testler

Bir diğer önemli husus, iyi entegrasyon ve birim testlerine sahip olmak.

Çoğu zaman dokümantasyon, hangi sınıfların ve metotların izole edildiğine odaklanır ve probleminizi çözmek için nasıl bir arada kullanıldıklarını gösterir. Testler genellikle birbirleriyle nasıl etkileşime girdiklerini göstererek bunları bağlam içine koyar.

Benzer şekilde, birim testleri çoğu zaman açıkça işlerin Mock out yapılması gereken açıkça dış bağımlılıklara işaret eder .

Ayrıca Test odaklı geliştirme kullanarak kullanımı daha kolay olan bir yazılım yazdığımı da biliyorum çünkü kullandığımdan beri kullanıyorum. İyi bir test çerçevesiyle, kodu test etmek daha kolay ve kullanımı kolay hale getirmek genellikle aynı şeydir.

Daha yüksek seviye dokümantasyon

Son olarak, sistem seviyesi ve mimari dökümantasyon hakkında yapılması gerekenler var. Pek çok kişi bu tür belgeleri bir wikide yazmayı veya Word veya başka bir kelime işlemcisini kullanmayı savunur, ancak benim için bu tür belgeler için en iyi yer, sürüm kontrol sistemi dostu olan düz bir metin biçiminde kodun yanındadır.

Kod içi belgelerdeki gibi, üst düzey belgelerinizi de kod deponuzda saklarsanız, güncel tutmanız daha olasıdır. Ayrıca, kodun XY sürümünü çıkardığınızda, belgelerin XY sürümünü de elde edersiniz. Ek olarak, eğer bir VCS dostu format kullanıyorsanız, dokümantasyonunuzu tıpkı kodunuz gibi dallamanın, farklılaştırmanın ve birleştirmenin kolay olduğu anlamına gelir.

Oldukça gibi reStructuredText (ilk) , bu kullanarak ondan hem html sayfalarını ve pdf belgeleri üretmek kolaydır olarak sfenks ve çok daha dostça LaTeX , henüz can hala şunlardır LaTeX matematik ifadeleri gereksinim duyduğunuzda.

Faheem'in neredeyse her noktasına itiraz edeceğim . özellikle:

1 / "Bilimsel geliştiricilerin yazılımlarını belgelemek için çok zaman harcamasını beklemenin gerçekçi olmadığını düşünüyorum". Bu, başarısız olan bir projenin reçetesidir ve yakında birincil geliştiricilere erişimi olmayan kimseyi kullanamaz. Büyük bilimsel bilgi işlem kütüphanelerinin (örneğin, PETSc veya anlaşma.II) 1000 sayfalık veya daha fazla sayfadan oluşan geniş bir dokümantasyonunun olması iyi bir sebeptir. Kapsamlı bir belgeniz yoksa, büyük bir kullanıcı topluluğunuz olamaz. Bununla birlikte, örnek kodların basit ve tek bir konsepte odaklanması gerektiğine katılıyorum.

2 / "yazarlar uygunsa yayın için bir bildiri yazmayı düşünmelidir". Bu genellikle pratikte mümkün değildir. Kişi, kavramlar ve algoritmalar üzerine yazılar yazabilir, ancak arayüz ve diğer tasarım kararlarında yazamaz. Bu tür makalelerin okuyucuları, uygulamanın ne yaptığı hakkında bir fikir edinir; Uygulamanın kullanıcıları ne fonksiyonlar çağırıp argümanların ne anlama geldiğini bilmelidirler. Bir kullanıcı olarak çoğu zaman eskisi olmadan yaşayabilir ve bir kütüphaneyi kara kutu olarak düşünebilir, ancak kimse yapamaz arayüz bilgisi.

Bu iyi bir soru. İlk yaklaşıma göre, kod kendi kendini belgelemeye çalışmalıdır. Yazılım komut satırı Yani eğer, örneğin, yapmanız gerekir executable --helpya da executable -hhatta executable(çalıştırılabilir argüman olmadan hiçbir şey yapmaz ise) ve kısa bir kullanım iletisi dönüşü var.

İkincisi, bilimsel geliştiricilerin yazılımlarını belgelemek için çok zaman harcamasını beklemenin gerçekçi olmadığını düşünüyorum, bu yüzden basit tutmanızı öneriyorum. Temel yöntemler ve seçenekler içeren kısa bir metin kılavuzu ve açıklamalı çalışma ve test edilmiştir.basitten karmaşığa (kullanım örnekleri çok önemli ve sıklıkla ihmal edilir) mezun olan kullanım örnekleri hiçbir şeyden çok daha iyidir ve çoğu bilimsel yazılımın sunduğundan çok daha fazladır. Ayrıca kullanım örnekleri hakkında bir evcil hayvan peeve eklemek istiyorum. Basit, basit demektir. Bu, bir yöntemi göstermeye çalışıyorsanız, okuyucuyu karıştırmak için on yabancı kavram ya da yöntem eklemeyeceğiniz anlamına gelir. Basit tutun ve açıklama ekleyin; böylece okuyucu, örneğin ne yapması gerektiğini bilir. Ayrıca manuel kullanım örneklerini bir şekilde bir test odasına bağlamayı öneririm, böylece kod değiştirildiğinde çalışmaya devam ederler. Aslında nasıl güzel bir şekilde yapıldığını bilmiyorum, bu yüzden lütfen beni eğitmekten çekinmeyin. Geliştiriciler daha fazla fantezi almak isterlerse, güzel biçimlendirme dilleri ve benzerlerini kullanabileceklerinden emin olun, man sayfaları vb. Ekleyin.

Üçüncüsü, yazarlar uygunsa yayın için bir bildiri yazmayı düşünmelidir. Bu genellikle tasarım kararlarını ele alır ve yazılım hakkında bir el kitabından daha yüksek bir bakış açısı verir veya yapması beklenenden daha yüksek bir perspektif verir. Bu, @Matt'ın bahsettiği tasarım kararlarının dokümantasyonunu ele alacaktır.

Tabii ki, hepsinin en önemli belgelendirme, gerektiğinde yorumlanması gereken kodun kendisidir. Bu, kodun ücretsiz bir yazılım olduğunu varsayar. Olmazsa, o zaman bilimsel yazılım olarak daha az kullanışlıdır (yöntemlerin nasıl uygulandığını göremediğiniz bir kara kutu kullanmak ister misiniz?) Ve ben bunu kullanmayacağım.

Verileri ve sonuçları nasıl belgeleyeceğiniz hakkındaki sorunuzu yanıtlamak için Python'un doctest modülü gibi bir şey öneririm . Bu, eğitimleri veya testleri otomatik olarak doğrulanabilecek şekilde yazmanıza olanak sağlar.

Okuryazar programlama ile ilgileniyorsanız, org-babel'e bir bakın . Emacs'ta org modunun bir parçasıdır ve bu nedenle size belgeler için çok çeşitli dışa aktarma seçenekleri (LaTeX, PDF, HTML, ODT) sunar. Emacs, görüntüleri arabellek içinde görüntüleyebilir ve LaTeX sözdiziminde matematiksel denklemler yazmanıza izin verir; böylece kendinizi düz metin belgelerine sınırlamak zorunda kalmazsınız.

Kaynak kodunuzdan otomatik olarak türetilen dokümanlar, güncel yani doğru dokümantasyona sahip olmanın temel bir bileşenidir. Belgelere yönelik geliştirici ilgisizlik nedeniyle kaç yıldır kaynak kodun gerisinde bulunduğunu gösteren belgeleri gördüm . Kolay çözüm, programcıların, daha görkemli faaliyetler lehine kaçınılmaz olarak öncelikli olarak belirlenecek bir posteriori çabası yerine, aynı yerde aynı anda yeni kodla birlikte dokümantasyon yazmasını kolaylaştırmaktır.

Seçmeye zorlanırsa, ayrıntılı ve doğru (yani geçerli) kaynak kod yorumlarına sahip olmayı tercih ederim, ancak yanlış bilgilerle dolu olan eski bir kullanım kılavuzundan başka bir kullanım kılavuzu yok .

Python'da, eksik veya hatalı biçimlendirilmiş belgeleri rapor edecek pep8 ve pep257 araçları vardır. Emacs için elpy, eksik belgelerden de şikayet edecektir. Kuralları docstringe Numpy reStructuredText ile takip etmek iyidir. Pep8, pep257 ve doctest ile test otomatik olarak çalışan py.test ve tox ile ayarlanabilir.