Köprü, dış kaynaklı kaynak kodu belgeleri [kapalı]

Neden hala ayrı bir belge yerine kaynak kodunun doğal dil tanımlarını (yani, bir kod satırının yazılma nedeni ) gömüyoruz?

Modern geliştirme ortamlarına (yüksek çözünürlüklü monitörler, çift monitörler, vb.) Sağlanan geniş gayrimenkul göz önüne alındığında, bir IDE, kaynak kodunun görsel olarak ayrıldığı - ancak kendinden bağlandığı - yarı kilitli paneller sağlayabilir. karşılık gelen yorumları. Örneğin, geliştiriciler kaynak kod yorumlarını hiper bağlantılı bir biçimlendirme dilinde yazabilir (ek yazılım gereksinimlerine bağlanır);

Hangi eksiklikler böyle bir yazılım geliştirme mekanizmasını engelleyecektir?

Soruyu netleştirmeye yardımcı olacak bir model:

İmleç kaynak koddaki belirli bir satıra (yukarıda mavi bir arka planla gösterilir) sahipse, imleçteki satıra karşılık gelen belgeler vurgulanır (yani diğer detaylardan ayırt edilir). Soruda belirtildiği gibi, imleç kaynak kodundan atlarken, belgeler kaynak koduyla kilit adımda kalacaktır. Bir kısayol tuşu "dokümantasyon modu" ve "geliştirme modu" arasında geçiş yapabilir.

Potansiyel avantajlar şunları içerir:

• Ekranlarda aynı anda daha fazla kaynak kodu ve daha fazla dokümantasyon
• Belgeleri kaynak koddan bağımsız olarak düzenleyebilme (dilden bağımsız olarak?)
• Birleştirme çakışmaları olmadan belgeleri ve kaynak kodunu paralel olarak yazın
• Üstün metin biçimlendirmesine sahip gerçek zamanlı köprü bağlantılı belgeler
• Farklı doğal dillere yarı gerçek zamanlı makine çevirisi
• Her kod satırı bir göreve, iş gereksinimine vb. Açıkça bağlanabilir.
• Her bir kod satırı yazıldığında belgeler otomatik olarak zaman damgası oluşturabilir (metrikler)
• Mimari diyagramların dinamik olarak dahil edilmesi, ilişkileri açıklayan görüntüler vb.
• Tek kaynaklı belgeler (ör. Kullanım kılavuzunun eklenmesi için etiket kodu snippet'leri).

Not:

• Belge penceresi daraltılabilir
• Kaynak dosyaları görüntülemek veya karşılaştırmak için iş akışı etkilenmez
• Uygulamanın nasıl gerçekleştiği bir ayrıntıdır; belgeler şunlar olabilir:
  • kaynak dosyanın sonunda tutulur;
  • konvansiyonla iki dosyaya bölünmüş ( filename.c, filename.c.doc); veya
  • tamamen veritabanına dayalı
• Köprü bağlantılı belgelerle, harici kaynaklara (StackOverflow veya Wikipedia gibi) ve dahili belgelere (yani, bir alt etki alanındaki iş gereksinimleri belgelerine çapraz başvuruda bulunabilecek bir wiki) ve diğer kaynak dosyalara (JavaDoc'lara benzer) bağlantı vermek istedim.

İlgili konu: Endüstrideki dokümantasyondan kaçınma nedir?

Bu sorun beni her zaman rahatsız ediyor ve sadece denememiz ve çözmemiz gereken yön hakkında bir fikrim var (bu soruyu nasıl bulduğum bu).

Kullanıcı belgelerini kaynak koduna dahil etmeye karar verdiğimizde bağlantılı belge sorununun yanlış olduğunu düşünüyorum. Tıpkı docco'nun yaptığı gibi.

Her şeyden önce, kod yorumlarını kullanıcı belgelerinden ayırmanızı sağlar.

Kod yorumları normalde kısa, süper kısa olduğunda normalde en iyisidir, bu yüzden neden ve nasıl çalıştığının bazı şiirlerini görmeden şeyleri yapan kodu okuyabilirim.

Kullanıcı yorumları, kitaplığınızı / API'nızı kullanmaya çalışan kişilere yöneliktir ve kullanım örnekleri, bunun neden uygulandığına dair açıklama veya kitaplığın nasıl genişletileceği hakkında talimatlar içerebilir. Bu tür yorumlar gerçekten ayrıntılı olma eğilimindedir.

Dokümanların düz metin olarak yazılması gerektiğine katılıyorum, bu yüzden satıcı sabit değil ve bir VCS'ye eklenmesi kolay. Ancak, kullanıcı belgelerini kaynak dosyada tutmanın en az iki nedenden dolayı büyük bir hata olduğunu düşünüyorum:

• Kodu okumak daha zor
• Yeterince esnek olmayan belgeler (aynı örnek kodu kullanan veya iki farklı kaynak dosyadan kod eklemeyi gerektiren bir belge sayfasına sahip iki belge sayfasına ihtiyacım olduğunu varsayalım).

Peki neden aynı dosyaya sahip olmak istiyoruz? Kimse belgelerini koddan senkronize etmek istemiyor. Ama yine de yapıyoruz ve özellikle Markdown'un büyük başarısı ile bir gün. Bence doğru yolda olduğunu, ancak kısa kalırsa, waaay kısa.

Kod yorumunu kullanıcı yorumuyla birlikte eklediğimizde, 2 yönlü bir bağlantımız var. Bu, hangi yorumun kodun hangi kısmına karşılık geldiğini kolayca görmemizi sağlar. Bazı kodların belgelenmemiş olup olmadığını da görebiliriz. Ne sunmuyorsa, yorumun güncellenip güncellenmediğini görmenin bir yoludur ve kodunuzun okunması zor olduğunda çok fazla şey olur (çünkü belgeler çirkinleşti).

Ya 2 yönlü bir bağlama yerine, tek bir yolumuz varsa? Kodu gösteren belgeler. İşaretleme koduna benzer özel komutlarla sahip olabiliriz:

Some documentation right here that explains the following code:
   @include_file <path/to/some/file>:<line_start>-<line_end>
or
   @include_file <path/to/some/file>
     @starts_with "some regexp or literal text to search"
     @ends_with "another regexp"
or
   @include_file <path/to/some/file>
     @class MyClass
     @method foo
or any combination or way of linking you could imagine

We can even have semantic in the directives:
   @explain_code <path/and/same/of/above>
   @example_code <path/and/same/of/above>
   @performance_notice <path/and/same/of/above>

Which would do basically the same, but it adds the intention of why
do we want to add this code in the first place, which could be 
used different by an IDE. 

Bunun bazı ilavelerle işaretleme avantajı vardır ve uygun araçlarla buna daha fazla değer katabiliriz.

Bunun homurdanma gibi araçlarla (saat görevinde bile) bağlandığını düşünün. Bir kaynak dosyanın ne zaman değiştiğini tespit edebilir, hangi belge dosyalarına bağlı olduğunu görebilir ve yorumlanan kodun değişmesi durumunda kullanıcıyı uyarabilir (veya bir yere işaretleyebilirsiniz).

404 Sayfa Bulunamadı

Kodla çalışırken yorumların kaybolmasını istemezsiniz ve kodu ve yorumları ayrı belgelere ayırdığınızda olan şey budur.

Ayrıca, yorum belgeniz ve kod belgeniz arasında sürüm oluşturmaya devam etmek, daha fazla acıya neden olur.

Yaptığım bazı öneriler gerçekten hoşuma gitti ama 1 dosyada kod ve yorum yaparken kolayca uygulanabilir.

Gördüğüm olası dezavantajlar:

• Bu özelliği uygulayan özel bir düzenleyiciye ihtiyacınız var

• Kod artık sadece düz metin değil, kullanımı kolay ve VCS'lere bağlı

• Kodla çalışmak için iki kat daha fazla ekran genişliğine ihtiyacınız var

Argümanlarınıza gelince:

Ekranlarda aynı anda daha fazla kaynak kodu ve daha fazla dokümantasyon

Ancak iki dosyayı yan yana görüntülemek istiyorsanız sakıncalı olabilir.

Belgeleri kaynak koddan bağımsız olarak düzenleyebilme (dilden bağımsız olarak?)

Bunun aslında bir dezavantaj olduğunu iddia ediyorum. Ben şahsen kodları modası geçmiş olmayacak şekilde koduna mümkün olduğunca yakın tutmaya çalışıyorum.

Birleştirme çakışmaları olmadan belgeleri ve kaynak kodunu paralel olarak yazın

Yine, muhtemelen bir dezavantaj. Dokümanlarınız kodla derinden ayrılırsa, bunları bağımsız olarak nasıl düzenleyebilirsiniz?

Üstün metin biçimlendirmesine sahip gerçek zamanlı köprü bağlantılı belgeler

Kodda ise, zaten gerçek zamanlıdır;) Köprülere gelince, tanımlamaya atlamak çoğu IDE'de zaten uygulanmaktadır.

Farklı doğal dillere yarı gerçek zamanlı makine çevirisi

Bunu neden düzenli yorumlarla / öğretilerle yapamayacağınızı anlamıyorum.

Her kod satırı bir göreve, iş gereksinimine vb. Açıkça bağlanabilir.

Bu konuda emin değilim ... Düzenli yorumlarla elde edilemez mi?

Her bir kod satırı yazıldığında belgeler otomatik olarak zaman damgası oluşturabilir (metrikler)

VCS-es bu tür bilgileri zaten sağlamıyor mu?

Bunu söyledikten sonra, yerleşimin kendisini çok seviyorum - ama dosya biçimini değiştirme ihtiyacını görmüyorum, düzenli yorumlardan oluşturmak o kadar zor değil. Bunu yapan bir sürü dokümantasyon üreticisi var, örneğin Docco ve Pycco veya Marginalia gibi halefleri .

İlk olarak, doktor yorumlarının kodla gitmesi gerekir - bunları başka bir yere taşımak, sadece sıfır kazanç için işleri inanılmaz derecede zorlaştırır. Ne gereği var!

Ancak yapılabilecek şey, bu gömülü yorumları alıp editörde gizlemek, bunları bir kabarcık veya araç ipucunda ya da gerektiğinde göstermektir. Umarım böyle bir yaklaşım insanları koda çok daha fazla dokümantasyon yazmaya teşvik edebilir.

Şu anda kod yorumlarını köprülere yerleştirebilir ve Doxygen veya Sphinx gibi araçları kullanarak koddan belge oluşturabilirsiniz. Ben sadece bu araçları daha iyi desteklemek için kod editörü tot bazı fantezi uzatma alacaktı sanırım.

Herhangi bir kod satırını bir hata izleyiciye veya gereksinimler aracına bağlamam, SCM için daha iyi bir iş. Ardından, bir göreve bağlı işlem başına kod düzenlemelerini görebilirsiniz. Kodda depolanan belgeleri hata izleyiciye de entegre etmem - yeni bir taneye geçmek istediyseniz vidalanırsınız (hmm, bu özelliğin şu anda TFS'ye eklendiğini görebilirsiniz) veya taahhüt geçmişinizi kaybettiniz (ki bu olur)

@Bogdan'ın zaten belirttiği gibi, birkaç tane ekleyeceğim:

• IDE'mi aynı anda 2 dosya olacak şekilde yapılandırdım. Önerdiğiniz özellik ile, temelde aynı miktarda bilgiyi görmek için 2 monitöre ve şu anda 2 ile yaptığım şeyi yapmak için 3 monitöre ihtiyacım olacak.
• Bir dosyaya göz atarken, yorumları hemen görmezsiniz ve tam olarak ne aradığınızı bilmiyorsanız, onu bulmak çok zordur.
• Bir dosyada arama yaparken, doğrudan (veya kolayca) yorumlarda arama yapamıyorum.
• Bazen çeşitli testler yapmam / ssh aracılığıyla canlı sunucuda kısa kod parçaları yazmam gerekiyor . Söylediğiniz işlevler VIM veya diğer komut satırı düzenleyicileriyle entegre edilmiş olsa da - büyük olasılıkla oldukça büyük sorunlar olacaktır

• Çoğu IDE, daraltma kodunu / yorumlarını destekler ve sonuç aşağıdaki gibidir:

  Normal yerine:

  

Yorumlara ihtiyacınız olmaması durumunda kodu daha okunabilir hale getirin.

Kaynak kodu ve dokümantasyonun yapılması gerektiği şekilde.

http://jasmine.github.io/2.3/introduction.html