Neden bu kadar çok kütüphanenin belgeleri yok / zayıf? [kapalı]

Benzer bir mantıkla kaynak projeleri açabilirsiniz How kendi tasarım veya mimarlık hakkında belgeler olmadan başarılı olmak? soru, merak ediyorum: Neden bu kadar çok kütüphane son kullanıcı belgelerinde bu kadar eksik?

Benim görüşüm şudur:

1. Çoğu kişi kaynak kodunu okumanın kaynak kod yazmaktan daha zor olduğunu kabul eder.
2. Belgeler olmadan, bu kütüphaneyi kullanabilmek için kütüphanenin kaynak kodunu okumak gerekir.
3. Bu nedenle, belgesiz kitaplığı kullanmak, kitaplığı sıfırdan yeniden oluşturmaktan daha fazla iştir.
4. Sonuç olarak, insanların kitaplığınızı kullanmasını istiyorsanız, belgelendirildiğinden emin olmanız daha iyi olur.

Birçok geliştiricinin doküman yazmayı sevmediğini biliyorum ve bunun sıkıcı bir iş olabileceğini kabul edeceğim. Ama bu önemli bir çalışma. Hatta bir kütüphanenin dünyadaki en iyi programcı arayüzüne sahip olmaktan ziyade iyi belgelere sahip olmasının daha önemli olduğunu söyleyebilirim. (İnsanlar her zaman boktan kütüphaneler kullanır; çok azı belgesiz kütüphaneler kullanır)

Oh, belgeleme dediğimde gerçek belgelemeyi kastediyorum. Sandcastle / Javadoc / Doxygen kazan plakası değil.

Sanırım çoğunlukla kendi sorunuzu cevapladınız: çünkü çoğu durumda geliştiriciler rahatsız etmeyecek. Sorun özellikle gönüllü projelerde yaygındır.

Yine de başka bir önemli sorun olduğunu düşünüyorum: Çoğu durumda, geliştiriciler kütüphanelerinin nasıl çalıştığına dair genel bir model geliştirmediler (veya sadece bu modeli açıkça ifade etmekte zorluk çekiyorlar). Ne yazık ki, bu modeli ve yazılım parçalarının birbirine nasıl uyduğunu belgelemek çoğu zaman belgelerin en önemli parçasıdır.

Tipik bir durumda, yazılanlar çok yüksek seviyeli bir genel bakışa sahiptir ("Bu harika şeyler yapmak için bir kütüphanedir!") Ve sonra çok düşük seviyeli bir açıklama (her işleve iletilecek her parametrenin tipi ve açıklaması) vardır. Ne yazık ki, şeylerin nasıl çalışması gerektiği, parçaların birbirine nasıl uyduğu vb.Genel teori hakkında nadiren bir ara seviye vardır. Bunun çoğu, geliştiricilerin genellikle belirli bir ayrıntı düzeyinde kodlayın. En azından bazı durumlarda gördüğüm, bu düzeyde belge yazması istenen geliştiriciler oldukça sorunlu buldular - birçoğunun kodu yeniden yazmak istediği noktaya kadar, bu düzeyde daha organize ve daha kolay açıklanacaktı detay.

Bu soyutlama düzeyinde iyi yazmak genellikle zordur - ve geliştirici bu soyutlama düzeyinde gerçekten düşünmediyse , kodu genellikle biraz utanç verici bulur ve mutlu olmadan önce yeniden yazmak isteyebilir hiç salıvermekle ilgili.

Bence bazen geliştirici kodda çok sarılmış olduğu için nasıl "açık" / nasıl çalıştığını ve neden başka kimseye açık olmayacağını göremiyorlar. Benzer şekilde, birçok ürün web sitesi, ürünlerinin ne kadar harika olduğunu söyler, ancak aslında ne yaptığını söylemeyin!

Cevabı kendiniz belirttiniz:

Birçok geliştiricinin doküman yazmayı sevmediğini biliyorum ve bunun sıkıcı bir iş olabileceğini kabul edeceğim.

Programcılar olarak kod yazmayı seviyoruz, ancak çok azımız da belge yazmayı seviyoruz.

İyi bir kodlayıcı iyi dokümantasyonun değerini bilse de, bunu doğru bir şekilde yapmak da oldukça zaman alır. Keyifli olmadığı ve uzun sürdüğü için, "daha sonra yapılacak" yığınına konur, böylece asla tatmin edici bir seviyeye ulaşmaz.

Bir yan not olarak, bir programcının kendi ürünlerine belge yazması da çok zordur. Sistemi çok iyi bildikleri için, bazı şeyler onlar için açıktır. Bu kısımlar, tüketiciye açık olmamasına rağmen, sıklıkla asla bahsedilmez.

Doküman yazma bir beceridir. Tüm beceriler gibi pratik gerektirir. Kod yazmak için harcadığımız zaman ve çaba hemen ödeniyor. Yeni özelliği, sabit hatayı, gelişmiş hızı görebiliriz. Belgelerin yazılmasında gecikme yaşanır. Yeni insanların kod üzerinde çalışması gerektiğinden veya kod aylar veya yıllar sonra işe geri dönersek uzun vadede yardımcı olur. Kısa vadeye odaklanmamız doğaldır.

Bence, iyi belgeleme yazma yeteneği, büyük programcıları vasat programcılardan ayıran temel özelliklerden biridir.

Doküman yazma konusunda en nitelikli kişi aynı zamanda bunu yapmak için en az motivasyonu olan kişidir:

o (ya da o):

• öncelikle bir kullanıcı yerine kütüphanenin bir bakıcısıdır. Kütüphane ne kadar küçük ve basitse işi o kadar kolay olur. Kodun yanı sıra yarım romanın tutulması işini daha da zorlaştırır,
• kütüphaneyi içeriden biliyor, bu yüzden belgelere ihtiyacı yok ,
• o bir programcı, doküman yazmak değil kod yazmak istiyor.

"Hmm, gerçekten bunun için bazı uygun belgeleri yazmak için birkaç saat harcamak gerekir" gitmek için daha az muhtemel kimse düşünemiyorum . Neden ki?

Ve elbette, bu kentsel efsanenin, otojenere edilmiş oksijen tarzı yorumların dokümantasyon açısından ihtiyacınız olan tek şey olduğu konusunda yardımcı olmuyor.

Bu nedenle, bir geliştiricinin aslında belge yazmaya istekli olduğu nadir durumlarda bile , geliştiricinin, bu kült tarafından gerekli olan tek şey, bu tür birkaç yorumu doldurduğunu düşünmek için beyin yıkaması ihtimali vardır. "işlev Foo getFoo()Foo türünde bir nesne döndürür ve Foo nesnesini almak için kullanılır".

Belgeler? Sersemletici belgelere ihtiyacımız yok!

Kodun nasıl çalıştığını biliyorum, neden kodumu belgelemek için zaman harcayayım? Bunun yanı sıra, bu projeyi Cuma gününe kadar yapmam gerekiyor ve bunu olduğu gibi yapmayacağım ...