Kod belgelerini nereye koyabilirsiniz?

Şu anda kod belgelerini yazmak için iki sistem kullanıyorum (C ++ kullanıyorum):

• Yöntemler ve sınıf üyeleri hakkındaki belgeler Doxygen biçimi kullanılarak kodun yanına eklenir. Bir sunucuda Doxygen kaynaklar üzerinde çalıştırılır, böylece çıktı bir web tarayıcısında görülebilir
• Genel bakış sayfaları (bir grup sınıfı açıklayan, uygulamanın yapısı, örnek kod, ...) bir Wiki'ye eklenir

Şahsen bu yaklaşımın kolay olduğunu düşünüyorum çünkü üyeler ve sınıflarla ilgili belgeler gerçekten koda yakınken, Wiki'de genel bakış sayfalarını düzenlemek gerçekten kolay (ve ayrıca resim, tablo, ... eklemek de kolay). Bir web tarayıcısı her iki belgeyi de görmenizi sağlar.

İş arkadaşım şimdi her şeyi Doxygen'e koymayı öneriyor, çünkü daha sonra içindeki her şeyle birlikte büyük bir yardım dosyası oluşturabiliriz (Microsoft'un HTML WorkShop'u veya Qt Assistant'ı kullanarak). Benim endişem, Doxygen tarzı belgelerin düzenlenmesinin (Wiki ile karşılaştırıldığında) çok daha zor olması, özellikle tablo, görüntü, ... eklemek istediğinizde (veya Doxygen için oluşturmanızı gerektirmeyen bir 'önizleme' aracı var sonucu görmeden önce kod?)

Büyük açık kaynaklı (veya kapalı kaynaklı) projeler kod belgelerini yazmak için ne kullanır? Bunu Doxygen tarzı ve Wiki arasında mı bölüyorlar? Yoksa başka bir sistem kullanıyorlar mı?

Belgeleri ortaya çıkarmanın en uygun yolu nedir? Bir Web sunucusu / tarayıcı veya büyük (birkaç 100MB) yardım dosyası aracılığıyla mı?

Kod belgeleri yazarken hangi yaklaşımı benimsiyorsunuz?

Tüm belgelerin iki yerine tek bir sistemde bulunması gerçek bir avantaj olabilir. Yedekleme ve geri yükleme, sürüm oluşturma, global arama, global arama ve değiştirme, çapraz bağlama ve yazdığınız gibi tüm dokümanları son bir belgeye koyma gibi şeyler, iki farklı bakım yapmanız gerekmediğinde genellikle daha az "sürtünme" ile çalışır örtüşen kapasitelere sahip sistemler.

Öte yandan, bu avantajların Wiki'nizin kolaylığından daha ağır bastığını düşünmelisiniz. Düzenleme / oluşturma / hassaslaştırma düzenleme / yeniden oluşturma döngüsü Wiki'nizle daha hızlı olabilir. Genel bakış sayfalarınızı ayrı bir doxygen alt projesi olarak tutarak doxygen ile bu döngüyü oldukça hızlı alabileceğinizi tahmin ediyorum. Sen yararlanabilirler dış bağlantı elbette bir "hızlı önizleme", yerini, ama bu yönde bir adım değildir doxygen yeteneklerinin. Bunu şimdiye kadar kendim yapmadım, ama sanırım sizin durumunuzda işe yarayıp yaramadığını bilmek istiyorsanız bunu kendiniz denemelisiniz.

Diğer projelerle ilgili olarak: Doxygen gibi bir aracın öncelikle kütüphane dokümantasyonu için olduğunu düşünüyorum. Üçüncü taraf bir kitaplık satıcısı değilseniz ve kitaplıklarınızı kullanan herkesin kaynak koduna tam erişimi varsa, doxygen gibi bir araca gereksinim şüphelidir. Örneğin ekibimizde, son kullanıcı dokümanları ve veritabanı modellerimizin dokümanları dışında, kod dışında neredeyse hiç harici dokümanımız yok. Bu tür belgeler için birincil araçlarımız , bize tatmin edici sonuçlar veren docbook ve fop'tur .

Önce Kod Belgelerini kullanın. Mümkünse Wiki ve diğer yöntemleri ekleyin

Biliyorum, bunu sürdürmek zor olacak.

Pratik cevap:

Pratik açıdan, geliştiricilerin yaptığı ilk şey, kodunu kontrol edin.

Bir geliştirici olarak, Wiki (ler), kılavuzlar gibi harici belgelere sahip olmayı seviyorum. Ancak, yaptığım ilk şey, kodu gözden geçirmek (bazen diğer geliştiricilerden, bazen kendiminkinden).

Birkaç proje ve müşteride çalışan bir geliştirici olarak, harici dokümantasyon eklemek için mümkün olduğunca yapıyorum, ancak çok fazla iş yüküne sahip olması yaygın ve wiki'yi destekleyemedi.

Bazen proje yöneticileri ve diğer patronlar dokümantasyonla ilgilenmez, bazen diğer geliştiriciler umursamaz.

Ve yapabileceğim en iyi şey, koduna bazı yorumlar eklemek.

İyi şanslar

Bazıları diğer sistemleri kullanır - örneğin Python's Sphinx'e bir göz atın , her şeyi inşa eden hepsi bir arada bir belge sistemine sahiptirler (ayrıca C / C ++ için de çalışır)

Her zaman belgelerin koddan ayrı olduğunu düşünüyorum, doxygen harika, ama API'ye genel bir bakış için değil, 'belgeler' değil. Bunun için bir wiki harika, ancak ASCIIDOC kullanmayı ve bunun sonuçlarını kodla birlikte kaynak kontrolünde saklamayı tercih ediyorum , çünkü esas olarak ondan diğer insanlara PDF'ler üretebildiğimden (örneğin test kullanıcıları, müşteri, vb.)

Doxygen, PDF, HTML, wiki sayfaları ve aklınıza gelebilecek hemen hemen her şeyi oluşturmanıza olanak tanır.

Benim kişisel tercihim, Doxygen ve wiki ve bir senaryo ya da ayrıldıklarında kontrol edilecek bir şey olması.

1.8.0 sürümünden beri doxygen , Wiki sisteminde olduğu gibi statik sayfa yazma deneyimini kolaylaştıracak Markdown'u destekliyor .

Hedef kitle

Bence bu soruyu cevaplarken bu dokümanı kimin okuması gerektiğini sormanız gerekiyor. Bir Geliştiricinin bir Kullanıcıya ve hatta bir İş Analisti'ne çok farklı ihtiyaçları vardır.

• Geliştirici olarak: incelenen kodla ilişkili belgeler, arayüz sözleşmesi gibi ayrıntılar ve kullanım örnekleri. Belki de iyi bir ölçü için bazı üst düzey belgeler ve protokol özellikleri.
• Kullanıcı olarak: Yardım menüsünden ulaşılabilen belgeler veya yazılımı kullanma hakkında erişilebilir bir web sitesi.
• İş Analisti olarak: belge olarak veya erişilebilir bir web sitesi olarak sunulan belgeler yararlıdır. Protokoller, üst düzey mimari ve kullanım örnekleri hakkında mütevazı bir ayrıntı en iyisidir.

Bakım

Bu dokümantasyonun kaynağının nereye yerleştirileceği, kitlenize ve kitleniz için kimlerin yazacağına bağlı olacaktır.

• Sadece geliştiricilerin evi mi var? Her şeyi koda yerleştirin. Güncellenmesi için teşvik edecektir. Belge değişikliklerini kod değişiklikleri kadar önemli olmaya teşvik eden bir kültür üzerinde çalışmanız gerekecektir.
• Bir ev geliştirici ve dokümantasyon yazarınız var mı? Sorumlulukları bölün. Geliştiriciler için geliştirici odaklı araçları kullanın, dokümantasyon yazarları için dokümantasyon yazarları araçlarını kullanın.

Mümkünse kod örneklerinin veya kullanım örneklerinin yürütülebildiğinden emin olun. Yürütülmelerini otomatikleştirin ve hataları dahili olarak işaretleyin. Muhtemelen bu sayfalar kötü veya kötü dokümanlardır.

Ayrıca, belgelerinizi yazmak için hangi araçları seçerseniz seçin, belgelerin belirli bir sürümünü kodun belirli bir sürümüyle ilişkilendirmek için güvenilir bir araca ihtiyacınız vardır. Bu, tek bir herdem yeşil konuşlandırmayla mutlu bulut topraklarında bile hala faydalıdır.

Belgeleri Entegre Etme

Bazı belgeler üretmek için entegrasyon gerekebilir, ancak yalnızca kullanıcının ihtiyaç duyduğu tüm belgelere erişmek için tek bir yer beklediğini unutmayın.

İş analisti, bir API spesifikasyonu, Tasarım Özellikleri ve Kullanım senaryolarından ayrı belgelerde veya bir web sitesinin ayrı bölümlerinde bulunmasından oldukça memnun.

Geliştirici, kaynaktan görünen her şeyi tercih eder, ancak tercihen aynı kasada olsa da, birkaç üst düzey tasarım belgesine ve kodun dışındaki ayrıntılı protokol spesifikasyon belgelerine sahip olmaktan oldukça mutludur.

Senin durumun

Dürüst olmak gerekirse, wikinizdeki belgeler muhtemelen kod tabanınızdaki belgelerle aynı tür değildir. Birleştirme de mantıklı olmayabilir.

Diğer yandan, ikisini entegre etmek birkaç basit yolla sağlanabilir.

• Kaynak dokümantasyon araçları (doxygen gibi) html üretebilir ve bir wiki bir web sunucusunda yaşar. Sadece wiki ile birlikte yerleşik bir versiyona hizmet etmek ve ikisi arasında bağlantı kurmak için basit bir entegrasyon noktası olurdu.
• Bazı wiki ürünleri, wiki'yi doğrudan kod tabanına check-in yapabileceğiniz bir dosyadan çalıştırmanıza izin verir. Bu, belgeleri kodla eşleştirirken basit bir wysiwyg aracı sağlar.
• Pdf gibi diğer formatlar da kullanılabilir, ancak bu kullanmak istediğiniz özel takımlara inecektir. Wiki'nizi markdown dosyalarına kazımak ve bunu doxygen (veya diğer araçlar) aracılığıyla beslemek mantıklı olabilir. Wiki ve kaynağı ayrı ayrı pdf olarak yazmak ve bir pdf birleştirme aracı kullanmak mantıklı olabilir.

Günün sonunda, hangi dokümantasyon sisteminin düşük bakım maliyetlerine sahip olduğunu bulun ve Geliştiriciler, İş Analistleri ve Kullanıcılar kitleniz tarafından görüldüğü gibi yüksek kaliteli bir ürün sunmanıza yardımcı olur. Bu gruplardan herhangi birini engelleyen her şey mutlaka ürünlerin kalitesini düşürecektir.

ASCII kullanıyorsanız, dokümantasyon verilerinizi gizleme işleminizi kaynak kodunuzun üst kısmında saklamalısınız! Ardından, yalnızca en akıllı (okuma: hak eden) kullanıcı dokümanlarınızı kullanma olanağına sahiptir.

Belgelerin iyi tanımlanmış, kolayca dışa aktarılabilir, taşınabilir bir formatta olması gerçek avantaj olabilir. Eğer Sfenks Sadece bir script görev olacağını tahmin diğer sistemine dönüştürmek gerekir pres kalıpları (olası). Verileri wiki'den çıkarmak (muhtemelen veritabanında tescilli bir formatta saklanmak acı verici olabilir).