Açık kaynaklı projeler için neden kod özeti bulunmuyor? [kapalı]


60

Dışarıda çok karmaşık açık kaynak projeleri var ve bazıları için bazı katkılar yapabileceğimi düşünüyorum ve keşke yapabilseydim, ancak giriş engelleri tek bir nedenden ötürü çok yüksek: Büyük bir proje hepsini anlamanız gerekir.

Tüm kodları okumanıza gerek yok (okursanız bile yeterli olmayacak) ve her satırın ne yaptığını ve neden olduğunu anlamanız gerekmiyor, çünkü kod muhtemelen modüler ve bölmelere ayrılmış durumda, bu nedenle soyutlamalar var, ancak hatta o zaman almak gerekir bakış Bildiğiniz böylece projenin nerede modülleri bulunmaktadır nerede bir modül diğeriyle arayüzü yapar tam olarak ne her modül yapmak ve niçin ve de dizin ve dosyaları oluyor bunlardan her biri.

Açık kaynak projelerinin web sitesinde veya bölümlerinde yabancılara kodlarını açıklayan belgelerde bulunabileceği bir bölümün adı olarak bu koda genel bakış diyorum . Bunun yararlanacak düşünüyorum katkı sağlayabilecek onlar gerçek, inşa edebileceğini yerleri tespit etmek mümkün olacaktır olarak, birincil kodlayıcılar her şeyi yazarken, akıllarını yeniden organize edebilecek şekilde, katılan ve yardımcı olacağını kullanıcıları onlar olduğu gibi, yaşadıkları hataları anlama ve daha iyi raporlama konusunda yardımcı olun ve hatta katkıda bulunabilirsiniz.

Ancak yine de bu "kod genel bakışlarından" hiç birini görmedim. Neden? Bunun gibi şeyler var ve onları özlüyorum? Tarif ettiğim ile aynı işi yapan şeyler? Yoksa bu benim için tamamen yararsız bir fikir mi? Çünkü benden başka herkes binlerce kodlu projeleri kolaylıkla anlayabilir mi?


7
Bir tasarım belgesi mi demek istiyorsun? Her projenin açıklamasını içeren nadir bir proje gördüm ancak bu genellikle bir API.
cırcır ucube

14
Neden? Çünkü sahipleri yüksek kaliteli dokümantasyon yazma ve sürdürme çabasına yatırım yapmak isteyen çok az sayıda proje var ve çoğu zaman faydalarını da anlayamayabilirler.
Alex D

9
Belgeleme, gerçek davranışa göre eski veya yanlış olabilir. Kod yapamaz. Bu yüzden çoğu proje kodu tercih ediyor.
Paul Draper,

5
Ayrıca bir mutfak sayacını 2 saat kadar ayarlarsanız ve Sadece Okunur (tm) özelliğini seçerseniz, bir proje hakkında ne kadar bilgi edebileceğinizi hafife almak kolaydır.
Kos,

43
Topluluk odaklı dünyaya hoş geldiniz: eğer yapılmadıysa, bunun nedeni bunu yapmadığın için :)
mgarciaisaia

Yanıtlar:


60

Çünkü bu tür bir belgeyi oluşturmak ve sürdürmek için ekstra bir çaba ve çok fazla insan ilgili faydaları anlamıyor.

Pek çok programcı iyi teknik yazarlar değil (çoğu olmasına rağmen); nadiren kesinlikle insan tüketimi için belgeler yazarlar, bu yüzden pratik yapmazlar ve yapmaktan hoşlanmazlar. Bir kod bakış Yazma sen kodlama üzerinde harcamak değil zaman alır ve başlangıçtaki yerine "Hepimiz üç kodlama varyantları destekleyen" diyebiliriz eğer bir projeye fayda daima büyüktür "Bizim kod gerçekten düzgün açıklamalar var!" Böyle bir belgenin daha fazla geliştiriciyi çekeceği ve uzun vadede daha fazla kodun yazılacağı fikri, tamamen yabancı değildir , ancak belirsiz bir kumar olarak algılanmaktadır; Bu metin gerçekten bir ortak çalışanı takma arasında bir fark yaratır mı, yapmaz mı? Şu anda kodlamaya devam edersem , Bu şeyi hallet.

Bir koda genel bakış belgesi aynı zamanda insanların kendilerini savunmada hissetmelerini sağlayabilir; Kararları gerekçelendirme gereği duymaksızın üst düzey kararları tanımlamak zordur ve çoğu zaman kararlar, gerçekte kendi yazılarını yazdıklarında “yeterince iyi gelebilecek” bir neden olmadan karar alırlar. Yukarıda bahsedilen ile ilgili bir etkiye de sahiptir: metnin değişen koda uygun şekilde güncellenmesi ek çabaya neden olduğundan, kodda kapsamlı değişiklikler yapılmasını engelleyebilir. Bazen bu istikrar iyi bir şeydir, ancak kod gerçekten orta düzeyde bir yeniden yazmaya ihtiyaç duyuyorsa, bir yükümlülüğe dönüşür.


6
Eh, cevap evet gibi görünüyor: gnunet.org/gnunet-source-overview
fiatjaf

5
Var olmasını istiyorsanız, yazmaya gönüllü olun. Açık kaynak kodlu projelerin tüm amacı, topluluğun bütünleşmeye değer olduğunu kabul ederek tabi ki, insanların yapabileceklerini ve katkıda bulunmaları gerektiğidir.
keshlam

8
@keshlam - eğer projeye zaten bir katkıda bulunuyorsanız mantıklı geliyor ... ancak kodun nasıl çalıştığı hakkında temel bir fikir edinmeye çalışan potansiyel bir katkıda bulunuyorsanız, yazmak için en kötü insansınız Bu belge ....
Jon Story 11

13
@JonStory Amacınız iyi bir konu ama pratikte bunun tam tersini de doğru buldum. Bazı projelerde belgesiz bir kod temeli öğrenirken yaptığım notlara dayanarak bir sürü dokümantasyon yazdım. Daha iyi bir dokümantasyondu çünkü görebildiğim API'dan başlamak ve daha derin ve daha derin kazmak zorunda kaldım. Kodu yazan geliştiricilerin kafasında zaten kodun bir modeli vardı ve bu nedenle birinin ne bileceği konusunda çok fazla varsayımda bulundular. Projede yeni olan biri tarafından yapılan belgeler, projede yeni olan biri için daha iyi belgeler olabilir .
Joshua Taylor

6
@JonStory: Pefectly belgelenmiş bir projeden daha azına dahil oluyorsanız, yine de bunu anlamaya başlamanız gerekecek. Notlarınızı projenin bir parçası yapmak, bir sonraki kişinin çalışmasını önlemeye yardımcı olur. (Hiç kimsenin, dokümanın varlığını veya yokluğunu katkıda bulunup bulunmama konusunda karar verici bir faktör olarak kullanacağını bilmiyorum.) Basitçe, javadoc yorumlarını (veya eşdeğerini) geliştirmek, katkıda bulunmaya başlamanın değerli bir yolu olabilir. Cidden, açık kaynağın ardındaki temel ilke bu: Yapılması gereken bir şey görürseniz, başkasını beklemekten çok yapın.
keshlam

14

Kuru, sert gerçek?

Belgelendirme yapılmaz, çünkü projeler onsuz yapabilir.

Açık kaynaklı projeler bile çoğu zaman katı bir rekabetle karşı karşıya kalır. Bu tür projelerin çoğu büyük omuzlarla başlamaz, parlak bir fikirle başlar, genellikle tek bir adam parlak fikirdir.

Bu nedenle, ücretsiz olarak işbirliği yapmayı teklif ettikleri halde, insan belgesellerini işe alma zamanını ve maliyetlerini karşılayamazlar. Belgelendirilmiş bir proje olan infact, genellikle ilk önce birkaç başlangıç ​​tekrarından geçmiştir. Genellikle 1-3 ile başlar, belki 5 kişi yeni fikirlerini yazıp dünyaya kavramın bir kanıtı olarak gösterir. Eğer fikir iyi olursa o zaman "takipçiler" ekleyebilirler, uzantıları, yeni seçenekleri, çevirileri sormaya başlayabilirler.

Tüm açık kaynaklı projeler bu aşamadan öteye gitmez, yalnızca halkın ilgisini çekmek için gereken "kritik kütleyi" kıranlar. Ayrıca, başlangıç ​​geliştiricilerinden birinin "büyük ve uzak düşünmesi" ve genişleme vb. Planlaması gerekir. Proje "evangelist" ve bazen de "proje yöneticisi" olabilir (diğer zamanlarda ise farklı insanlar). Bu, projeyi kanıtlamaktan, sektörün kanıtlanmış gerçeğine kadar kanıtlamak için gerekli bir adımdır.

O zaman bile, proje yöneticisi dokümantasyon oluşturmamayı seçebilir.

Dinamik, büyüyen bir proje hem yavaşlardı, hem de belgeler, kodların gerisinde kalırken, gerçekten güçlenirken, çevirileri, seçenekleri uygulamak, yöneticileri takmak ...

Genelde olan şey şudur:

  1. Projenin ne olduğu ve nereye gideceği (ünlü "yol haritası") hakkında kısa bir tanıtım belgesi hazırlanır.
  2. Mümkünse, bir API geliştirilir ve bu, temel kodun toplamı üzerinden "belgelenmiş kod" olarak seçilir.
  3. Özellikle API, ayrıca diğer kodlar yeniden biçimlendirilmiş ve "PHPdoc" / "Javadoc" vb. Özel yorumlar eklenmiştir. Harcanan zaman ve ödül arasında iyi bir uzlaşma sunarlar: mütevazı bir programcı bile, fonksiyonlarını tanımlayan tek bir linerin nasıl yazılacağını bilir, parametreler de "otomatik" olarak belgelenir ve bütün bunlar ilgili koduna bağlanır ve böylece dokümantasyondan kaçınır " desyncing "ve davranış geliştirme gecikmiş.
  4. Çoğu zaman, bir forum oluşturulur. Son kullanıcıların ve programcıların birbirleriyle konuşabilecekleri güçlü bir sosyal medyadır (ve akranları arasında, muhtemelen "sadece devs" alt forumlarında). Bu, birçok bilginin toplum tarafından yavaşça ortaya çıkmasını ve konsolide edilmesini sağlar (okuma: geliştirici ekibine ağırlık koyma) SSS ve NASIL'lar.
  5. Gerçekten büyük projelerde, bir wiki de üretilir. "Büyük projeleri" belirtiyorum çünkü bunlar genellikle bir wiki (bir dev yapar) oluşturmak için yeterince takipçileri olanlar ve aslında bunu "çıplak kemikler" in ötesinde dolduruyorlar (topluluk yapar).

2
VAY!! iki farklı dünyada yaşıyoruz (ve çalışıyoruz). Nerede çalışıyor olursanız olun, oradan hızlıca çıkın ve doğru bir şekilde yapıldığı bir şirket (çok sayıda var) bulun çünkü bu size gerçekten para kazandırır. Sivri başlı yöneticilerin / kovboy kodlayıcıların size aksini söylemeye çalışmasına asla izin vermeyin.
01:14 de Mawg

6
+1, neredeyse tüm puanlarınıza katılıyorum, kesinlikle reddettiğim tek ifade, parametrelerin "otomatik" olarak belgelenmesidir . Yalnızca sözdizimi / tür kısıtlamaları yerine açıklamalar düşündüğümüzde hiçbir şey "otomatik olarak belgelendirilir"; Tarzında oluşturulan bir yorum X'i döndürür. Bir getX yöntemi yararlı bir dokümantasyon değildir, sadece fazladan bilgi içermeyen bir dolgudur .
VEYA Eşleştiricisi

3
@Mawg iyi dokümantasyon sağlamak bir yatırımdır, gelecekteki (umarım) daha fazla katılımcının karşılığında geliştirici zamanını ve bazı diğer avantajları beklersiniz. Ancak türünün çoğu gibi, projenin başarılı olması için iyi bir şansın olduğunu ve çoğu yazılım projesinin başarısız olduğunu biliyorsanız, faydalı olacaktır. Başarılı projelerde belgeleme eksikliğinden şikayet ettiğinizde hayatta kalma önyargısının farkında olmanız önemlidir.
congusbongus

Bu projelerin belgelenmedikleri için başarısız olması mümkün değil mi? Ve belgeye göre, demek istediğim, klavyede oturmaktan ve vurmaktan ziyade anlamaktır. İşte bir proje yaşam döngüsü için tahminim, tüm rakamlar +/-% 5. Ön şeyler (gereksinimler ve kullanım durumları, mimari, ayrıntılı tasarım)% 50,% 10 ila 15 kodlama, geri kalan testler. "Planlamayı başaramazsan, başaramazsın"
Mawg

6

Açıkladığınız gibi genel bakış belgeleri ticari projelerde bile nadirdir. Geliştiriciler için çok az değere sahip ekstra çaba gerektirir. Ayrıca geliştiriciler gerçekten gerekmedikçe dokümantasyon yazmazlar. Bazı projeler teknik yazı yazarken iyi üyelere sahip olduğu için şanslılar ve sonuçta iyi kullanıcı belgelerine sahipler. Geliştirici belgeleri varsa, kod değişikliklerini yansıtacak şekilde güncellenmesi olası değildir.

İyi organize edilmiş herhangi bir projenin, göreceli olarak açıklayıcı olan bir dizin ağacı olacaktır. Bazı projeler bu hiyerarşiyi ve / veya seçilme nedenlerini belgeleyecektir. Pek çok proje göreceli olarak standart kod düzenlerini takip eder, bu yüzden birini anlarsanız, aynı düzeni kullanan diğer projelerin düzenini anlayacaksınız.

Bir kod satırını değiştirmek için, çevre kodunu sınırlı bir şekilde anlamanız gerekir. Bunu yapabilmek için kodun tamamını tam olarak anlamak zorunda kalmamalısınız. Bozulan bir işlev türü hakkında makul bir fikriniz varsa, dizin hiyerarşisinde hızlı bir şekilde gezinmek genellikle mümkündür.

Bir kod satırını değiştirmek için satırın bulunduğu yöntemi anlamanız gerekir. Yöntemin beklenen davranışının ne olduğunu anlıyorsanız, düzeltici değişiklikler veya işlevlerde uzantılar yapabilmeniz gerekir.

Kapsam sağlayan diller için, özel kapsamlı yöntemleri yeniden değerlendirebilirsiniz. Bu durumda, arayanların yanı sıra refactor yöntemini veya yöntemlerini de değiştirmeniz gerekebilir. Bu, kod tabanının daha geniş, ancak yine de sınırlı bir şekilde anlaşılmasını gerektirir.

Bu tür değişikliklerin nasıl yapılabileceğinin bir örneği için tinyca'ya SHA-2'yi ekleme makaleme bakın. Arayüzü oluşturmak için kullanılan kodun son derece sınırlı bir anlayışına sahibim.


1
Buradaki önemli nokta, değişiklik yapmak için kod hakkında ne kadar bilgi sahibi olmanız gerektiğini belirtmek değildi. Tabii ki bu bir çok şeye bağlı olacaktır, ancak hiçbir zaman tüm kodu anlamak zorunda kalmayacaksınız, ne de genel bir bakış size bu anlayışı verecek, ancak değiştireceğiniz kod satırını bulmak için bile belli bir bilgiye ihtiyacınız olacak. genel proje yapısı.
fiatjaf

+1 Açık kaynak konusunda özel bir şey yok. 10 yıldan fazla bir süredir sektörde çalışan deneyimimde bir zamanlar genel bir belge görmedim. Genelde olan şey, işverenlerin istihdamınızın ilk ayının sıfır üretkenliğe sahip olmasını beklemeleridir çünkü kod tabanını inceliyorsunuz. "Genel bakış" genellikle iş arkadaşlarınızla ilgili sorular sormak için uygulanır
slebetman

5

Bunun gibi şeyler var ve onları özlüyorum? Tarif ettiğim ile aynı işi yapan şeyler?

Çeşitli yüksek profilli açık kaynaklı yazılım projelerinin ayrıntılı açıklamalarını sağlayan Açık Kaynaklı Uygulamaların Mimarisi adlı mükemmel bir kitap var . Ancak, hayal ettiğiniz rolü tam olarak doldurup doldurmadığından emin değilim, çünkü birincil izleyicisinin, kitapta yer alan projelere yeni katılımcılar değil, kendi uygulamalarını oluştururken takip edecek kalıplar arayan geliştiriciler olduğunu düşünmüyorum. (Yine de orada yardımcı olabileceğinden eminim).


Bu bir yorum gibi daha fazla okur, Nasıl
Cevaplanır

4
Yorumunuzu yapıcı bulmuyorum. Özellikle, eksik olduğunu düşündüğünüz şey nedir? Buradaki diğer cevapların birçoğu, geliştiricilerin genel bakış belgelerini yazmamasının olası nedenleri hakkındaki uzun spekülasyonlardır. İyi bir genel bakış belgelerine özel bir örnek verdim.
bjmc

1
Sorulan sorunun cevabını hissediyorum, "Açık kaynaklı projeler için neden kod özeti yok?"
tatarcık

3
Ben aslında, orada ne zaman yazıldığı gibi soruya doğru cevap vermek mümkün değildir iddia ediyorum olan bazı açık kaynak projeleri için kod Özetler. Cevabımı, kullanıcının kaçırmış olabileceği örnekler için bir talebe cevap vermeyeceğimi açıkça belirtmek için düzenlemiştim.
bjmc

1
Yazılan soru, “Bunun gibi şeyler var mı ve onları özlüyorum mu?” Diye soruyor. Bu cevap kesin olarak cevap verir ve bu kod genel görünümlerinin mevcut bir koleksiyonuna işaret eder. Bu nedenle, sorunun büyük (ve uygun) bir cevap olduğunu düşünüyorum.
Jim Garrison

4

Çünkü açık kaynaklı teknik yazarlardan çok daha fazla açık kaynaklı programcı var.

Dokümantasyon güncel kalmak için bakım ve zaman alır. Belgeler ne kadar hacimli olursa, o kadar fazla zaman alır. Kodla senkronize olmayan belgeler de işe yaramaz olmaktan daha kötü: ifşa etmek yerine yanlış yönlendirir ve gizler.

İyi bir şekilde belgelendirilmiş bir kod tabanı, daha az belgelenmiş bir belgeden daha iyidir, ancak belgeler ilk etapta kodu yazmak kadar kolay olabilir. Öyleyse sorunuz şu, iyi belgelenmiş bir kod tabanına mı, yoksa iki katı büyüklükteki bir kod tabanına mı sahip olmak daha iyidir? Kod, geliştiricilerin katkısına değecek ya da getirmeyebilecek katma değerlere değdiğinde, belgeleri güncel tutmanın maliyeti nedir?

Nakliye kodu kazanır. Gönderim kodu dışındaki şeylere harcanan çabanın azaltılması, kodun daha sık gönderilmesini sağlayabilir ve kaynakları tükenmeden önce gönderilmesi daha muhtemel olabilir.

Bu, nakliye meselesi yanında olan şeyler anlamına gelmez. Dokümantasyon, projeye değer katar ve yeterince büyük bir projeyle, başka bir geliştirici eklemenin bağlantı maliyeti, bir belgeleyici eklemekten çok daha yüksek olabilir. Ve belirtildiği gibi, dokümantasyon projeye yatırımı artırabilir (yeni programcıların katılımını kolaylaştırarak).

Ancak, hiçbir şey başarıya benzemez: işe yaramayan veya ilginç bir şey yapan bir proje de geliştiricilerin ilgisini çekmez.

Bir kod tabanının belgelenmesi bir meta-çalışma şeklidir. Çok fazla bir değeri olmayan bir kod tabanını tanımlayan süslü belgeler yazmak için çok zaman harcayabilir veya kod tabanınızdaki tüketicilerin istediği ve kod tabanınızın değeri olan şeyler yapmak için zaman harcayabilirsiniz.

Bazen işleri zorlaştırmak, görevi daha iyi yapanları da yapar. Ya projeye daha fazla bağlılık nedeniyle (mimariyi öğrenerek saatlerce zaman harcayarak) ya da beceri yanlılığı nedeniyle (eğer zaten ilgili teknolojide uzmansanız, hızlanmaya çalışmak daha hızlı olacaktır, bu nedenle eksiklik engeli) bu tür belgeler daha az önemlidir: bu nedenle daha fazla uzman takıma katılır ve daha az yeni başlayanlar için).

Son olarak, yukarıda belirtilen nedenlerden dolayı mevcut geliştiricilerin kod bazında uzman olmaları muhtemeldir. Yardımcı olmuyor söz konusu dokümanları Yazma onları zaten bilgi sahibi olarak, çok kod tabanını anlamanıza, sadece diğer geliştiriciler yardımcı olur. Açık kaynak geliştirmenin büyük bir kısmı, geliştiricinin kodda sahip olduğu "kaşıntıyı çizmekten" kaynaklanmaktadır: geliştiricinin nadiren kaşıntı duyduğunu söyleyen belgelerin eksikliği.


+1 "belgeler ilk etapta kodu yazdığınız sürece kolayca alabilir" - veya daha uzun!
Marco, 14

-1

Ekstra çaba göstermenin yanı sıra , bazı açık kaynaklı projeler, yöneticileri için serbest meslek sahibi olmak için (bir şeyleri uygulamak veya eğitimler düzenlemek) amaçlı olarak belgesellerini sakatlıyorlar. Yalnızca kod genel bakışları yoktur, ancak API'ları ve eğiticileri de kötüdür veya pek çok şeydir.

Sadece oldukça popüler olanı adlandırmak için: bluez. İyi şanslar bulmak için iyi bir şans, o zaman yakındaki cihazları taramak için.


8
Kötü belgelendirilmiş açık kaynaklı projeler için kaç örnek listeleyebildiğiniz önemli değil, bence, “belgelerini bilerek sakatladıkları” iddiasının kesin kanıtlarla desteklenmesi gerekiyor (ve o zaman bile muhtemelen genel açıklama).
VEYA Eşleştiricisi

@ ORMapper "Bluez - en büyük linux gizemi" ile başlayalım . Linux için tek bluetooth kütüphanesi olarak, dokümantasyon olmadığına inanmak zor, çünkü ekstra bir çaba. Cehennem, doxygen var ve basit öğreticiler yazmak ne kadar zor?
BЈовић

@ ORMapper Sonra linux çekirdeği var. Bir şeyi kaçırıyorsanız (bir çekirdek sürücüsü gibi), şirketinizin uzmanlığı eksikse, birini işe alabilir veya bir serbest meslek sahibi veya sizin için yapacak bir firma bulabilirsiniz. Yani, açık kaynak, ancak bir bedeli ile geliyor
BЈовић

@ ORMapper Daha sonra kağıt biçiminde dokümantasyon ile açık kaynak projesi var. Yani bir kitap alıyorsunuz ve başka bir belge yok. Bu belge sakatlanıyor mu değil mi?
BЈовић

2
Ne pahasına olursa olsun , en azından kasıtlı olup olmadığını merak etmek için ayakkabıcı dokümantasyondan yeterince karlı çıktım . Yarı zamanlı belgeleri çevrimiçi olarak sunan aynı gruplar size bir kitap veya eğitim sınıfı satmaktan çok mutlu olduğunda, bu sonuca ulaşmak için çok fazla alaycılık gerektirmez.
cHao
Sitemizi kullandığınızda şunları okuyup anladığınızı kabul etmiş olursunuz: Çerez Politikası ve Gizlilik Politikası.
Licensed under cc by-sa 3.0 with attribution required.