Kod belgelerini otomatik olarak oluşturmak için herhangi bir mantıklı sebep var mı? [kapalı]


60

Otomatik dokümantasyon oluşturma, çeşitli araçlarla yapılabilir; GhostDoc daha öne çıkanlardan biridir. Ancak, tanım gereği, ürettiği her şey gereksizdir. Bu vb yöntemlerle, sınıflar ve çıkışların İngilizce isimlerinin bir görünüm alır olabilir daha verbosely bunları açıklar. En iyi durumda, okuyucunun zaten kafasında yapabileceklerini yapar ( buradan alınan örnekler ):

/// <summary>
/// Initializes a new instance of the <see cref="Person"/> class.
/// </summary>
public Person() ...

En kötüsü, isimlerin anlamını buluşsal olarak çözme girişimi sırasında yanıltıcı olan tuhaf belgeler üretebilir:

/// <summary>
/// Riches the text selection changed.
/// </summary>
/// <param name="richTextBox">The rich text box.</param>
private void RichTextSelection_Changed(System.Windows.Controls.RichTextBox richTextBox) ...

Görünen o ki, GhostDoc ile ilgili tutum “ bir tür resmi XML belgesine sahip olmak gerçekten doğal olarak daha iyi” gibi görünüyor , ancak bu belgeler% 100 gereksiz olduğunda neden? En iyi ihtimalle bir ton boşa harcanmıyor mu?

İş yerimde, her şeyi belgelememiz gerekiyor ve neredeyse her zaman GhostDoc'un otomatik olarak oluşturulan belgeleriyle. Bunu yapıyor musunuz ve gerçekten belgeleri kendiniz yazmayacaksanız kodu sadece belgelenmemiş bırakmak için rasyonel nedenler var mı?



5
DLL'lerinizi yeniden kullanıyorsanız ve IntelliSense'in hangi yöntem ve parametrelerin yaptığıyla ilgili ipuçlarını korumak istiyorsanız, her bir sınıf, yöntem ve parametre hakkında yorum yapmanız gerekir. Aksi takdirde, proje patlayacak ve XML oluşturulmayacak. Bunun gibi otomatik olarak oluşturulan yorumları kullanarak gülünç tembel bir yaklaşım buluyorum.
krillgar

11
Reduntant dokümantasyon yapar, böylece geliştiriciler bundan rahatsız olur ve doğru dokümantasyonu doldurur. Her yerde akıl oyunları.
Kroltan

2
bazen dokümanı verebilirsiniz ancak kodu veremezsiniz
Leo

2
Kısa cevap: Hayır.
Thomas Eding 10:14

Yanıtlar:


14

[...] her şeyi belgeleyin ve neredeyse her zaman GhostDoc'un otomatik olarak oluşturulan belgeleriyle. Bunu yapıyor musunuz ve gerçekten belgeleri kendiniz yazmayacaksanız kodu sadece belgelenmemiş bırakmak için rasyonel nedenler var mı?

Hayır. GhostDoc tarafından oluşturulan dokümantasyon bir kazan plakasıdır (IDE'de yeni bir OO sınıfı oluşturmanın benzer bir yapıcı veya bir sınıf için bir sınıf için boillatı yaratmasına benzer). Belgelerin yararlı kısmı, kazan plakasını ekledikten sonra izleyeceği kısımdır.

İş yerinizdeki her şeyi belgelemek zorunda olsanız da , iş arkadaşlarınız onun etrafında mükemmel bir yol bulmuş gibi görünüyor: sadece rol yapın.


-1. Sadece numara mı yaptı? Bir daha asla kullanılamayacak bir proje için harika olabilir. Karmaşıklık "merhaba dünya" ndan büyükse ve bir projeyi altı ay içinde almayı planlıyorsanız, tek bir proje için bile bir miktar belgelendirme / yorum gereklidir. Düzinelerce, hatta yüzlerce insanın yer aldığı bir projede, belgelendirme / yorum yapılmaması projeyi öldürebilir.
David Hammen

14
@DavidHammen, yeterince belgelendirme olmadığı için bir projenin ölebileceğini çok iyi biliyorum. Ayrıca, "sadece pretent", OP'ye bir öneri değil, OP'nin meslektaşlarının bir eleştirisiydi.
utnapistim

73

Statik olarak yazılmış bir dilde Javadoc tarzı dokümantasyon yazarlar için değildir, tüketiciler içindir. Otomatik üretim, yazarların diğer kişilerin kullanması için gerekli belgeleri sağlamasını kolaylaştırır.

Statik olarak yazılmış bir dil kullanıyorsanız ve üçüncü taraf tüketimi için bir kütüphane yazmıyorsanız, otomatik üretme sizi çok fazla satın almaz ve benim deneyimimde nadiren kullanılır. Dinamik olarak yazılmış bir dil kullanıyorsanız, javadoc tarzı belgeler genellikle yalnızca dahili kullanım için bile türleri belgelemek için kullanılır, ancak otomatik üretme türleri bilmez;

Her iki durumda da, otojenerasyonu bitmiş bir ürün üretmek olarak düşünmeyin. Bunu sizin için kazan plakasını üretmek olarak düşünün, bu nedenle manuel olarak yaptığınız tüm değişiklikler önemlidir.


26

Kod belgelerini otomatik olarak oluşturmak için herhangi bir mantıklı sebep var mı?

Kimin bakış açısından?

Şirketi ya da dev grubu yönetiyor olsaydım, iyi bir sebep olmazdı. Çılgınca "yorumlar nedenini açıklamalı " kampındayım. İnsanları sınıflara / fonksiyonlara / özelliklere yorum yapmaya zorlamak değersizden daha kötü, çünkü güncel olmadıkları için okuyucuyu yanlış yönlendiriyorlar, okunabilir kod yapmamak için bahane olarak kullanılıyorlar, vb. Bu yorumlar hem yazarken, hem de kodu okurken hem de onların neden olduğu hataları boşa harcıyor. Bazıları, JavaDoc stili API belgelerinin yorum yapmak için bir neden olduğunu iddia edecektir, ancak bu argüman altında bile, kodunuzun küçük bir kısmı genel API'nin bir parçası olmalıdır ve JavaDoc, gerçek API belgelerinin yerine geçmez.

Bir geliştirici olarak, benim görüşüme rağmen, bu yerlerde yorum gerektiren birkaç yerde çalıştım . Kimsenin kullanmayacağı bir saçmalık yazmak için zamanım ya da sabrım olmadığı için bunun yerine GhostDoc'u kullanıyorum. Bu, benim için önemli olan şeyleri yapmak için zaman harcamamı sağlıyor. Değişen şirket politikasından çok daha verimli.

GhostDoc'u kullanırken bulduğum bir diğer iyi şey de, isimlerimin iyi olduğunu kontrol etmemesi. GhostDoc bir işlev için uygun belgeler oluşturamazsa, işlevim veya parametre isimlerimin zayıf olabileceği bir koku. Aracı sadece bunun için kullanmasam da , zamanımı boşa harcamam gerekirse, bu küçük bir yan etki.


1
Bunun dışında benim örneğim, GhostDoc’un, adının gerçekten kötü olmadığı durumlarda bile, uygun belgeler üretemeyeceğini gösteriyor.
Jez,

11
Evet, bazı menajerler "tüm kodumuzu belgeliyoruz" ilan ediyor ve diğer menajer sonuçta her şeyin harika olduğunu düşünüyor. Bilgilendirilmemiş bu şekilde kalır, ama yine de mutlular.
JeffO

3
@jez - Tabii, bu sadece bir koku. Bazen doğru, bazen değil.
Telastyn

1
Bir soruya cevap vermek. Güzel;)
Pierre Arlaud

@Jez Adının gerçekten o kadar da kötü olmadığını söylediniz. Ancak, bir seçim nesnesine aitse ve parametresinin türünden sonra adlandırılmamışsa , RichTextSelection_Changedyöntemi kullanmak daha kolay olabilir . Telastyn'ın dediği gibi, tasarımınız için doğru ya da yanlış olabilecek bir koku ve önerilerim muhtemelen GhostDoc çıktısını iyileştirmeyecek.
14'te

21

EDIT : Orijinal soruyu yanlış anladım; Her ne kadar dokümantasyon üretmenin (kodsuz belgeler ) çok değerli olabileceğini düşünmeme rağmen ( aşağıdaki Doxygen ile ilgili orijinal cevaba bakınız), otomatik olarak üreten yorumlar (GhostDoc'un aslında yaptığı bir şey) bana çılgınca geliyor. Bir programın neden bir programın yorumlanmamış kaynak kodunu okuyabilmesini ve gerçekten netleştirecek yorumlar yazmasını beklediğini anlayamıyorum.

Son derece "akıllı" bir yorum oluşturma yardımcı programının belirli kalıpları tanımak ve "nasıl" tarzı yorumlar üretmek için programlanabileceği düşünülebilir ; örneğin, Knuth'un varyans hesaplama algoritmasını tanıyabilir ve nasıl çalıştığını ve saf algoritmanın neden uygun olmadığını açıklayan bir yorum yapabilir. Belki de böyle bir yardımcı program, kanonik nesne yönelimli tasarım kalıplarını tanımak için programlanabilir (örneğin Soyut Fabrika) ve hangi kalıpların kullanıldığını ve hangi sınıfların hangi rolleri oynadığını belirten yorumlar ekleyebilir.

Ancak benim görüşüme göre, en yararlı yorumlar bir şeyin "nasıl" olduğunu açıklamıyor, çünkü kodun kendisi bunu göstermeli, ancak " neden ", "neden" i belli bir şeyin yapıldığını açıklıyor. David Hammen tarafından aşağıdaki yorumlarda belirtildiği gibi, "neden" yorumları üretmek için bir yardımcı programın "programcının aklını okuması" gerekir. Açıkçası bu imkansız.

Bununla birlikte, verilen örneklere dayanarak, GhostDoc'un gerçek "nasıl" tarzı yorum oluşturma görevini bile yerine getirmediği anlaşılıyor. Ne yana yüzden, yararsız daha kötü Bence, içinde olduğu vermez oluşturmak anlamsız ve (ikinci örnekte olduğu gibi) yanıltıcı olabilir.


Orijinal cevap: neden otomatik dokümantasyon çıkarma ve biçimlendirme iyi bir fikirdir?

Yazılım ekibim Doxygen kullanıyor. Bunun birincil nedeni , kod özellikleri / davranış / etc kaynak kodu olmayan (yani programcı olmayanlar tarafından okunabilen) dokümantasyona ihtiyacımız olması, ancak bunu kaynak kodun kendisiyle bütünleştirmenin daha iyi bir uygulama olduğunu düşünüyoruz. ikinci bir belge olarak saklayın . Bu, dokümantasyonu kaynak kodla senkronize tutmamıza yardımcı olur (elbette tamamen sağlanamamış, daha az otomatikleştirilmiş olsa da) ve yazma belgelerinin genel giderini en aza indirir (çünkü bir kod parçası için dokümantasyon önemsizce dahil edilebilir). kodun kendisini içeren dosya).

Dolayısıyla, Doxygen kullanımımızın odağı, kodun kendisinden bilgi çıkarmak değil, kaynak kodun belgelerini kaynak kodunun kendisine mümkün olduğunca yakın tutmaktır.

Bu aynı zamanda hem kod tabanımızı tanımlayan bir "işlem teorisi" hem de yazılım ürününü tanımlayan ancak aslında herhangi bir gerçek "kod dokümantasyonu" içermeyen birkaç "sürüm notu" setini oluşturmak için tek bir araç kullanmamızı sağlar. Tipik anlamda.

Neden kodumuzun davranışının kaynak kod dışı dokümantasyonuna ihtiyaç duyduğumuza gelince, iki neden var:

  • Ürünümüz sadece bir yazılım değildir; Bazı fantezi lazerler ve akışkanlar dahil, birçok donanım bileşenini birleştiren karmaşık bir araçtır. Kodumuzun içindekilerin tam olarak nasıl davrandığını tam olarak anlayabilmeleri için yazılım altyapısına sahip olmayan mühendislere ihtiyacımız var ve onlara "kaynak kodu oku" diyerek bunu başaramayacağız.
  • Bazıları şirket içi, bazıları da federal hükümet tarafından yasal olarak uygulanan, bazıları içsel olarak görevlendirilen birkaç kalite düzenlemesine uymalıyız. Kalite süreci son derece değerli ve faydalı olmasına rağmen (veya en azından olabilir), bir kısmı yazılım ekibinin bu tür ayrıntılı bir dokümantasyonunu sağlama görevini üstlenmeyen ihmal edilemez bir miktar ek yükü içerir. Yine, bu belgelerin kodun kendisiyle entegrasyonu ek yükü en aza indirir ve belgeleri güncel tutmamıza yardımcı olur.

İkinci madde işaret noktasının, bazı kaynak kodların (kalite ne olursa olsun) her bir kaynak kod parçası için var olduğunu bilmenin güvencesini (/ övünme haklarını) bilmek isteyen yöneticiler hakkında birkaç başka cevabın verdiği noktaya oldukça benzer olduğunu unutmayın; Bununla birlikte, bu şekilde çerçeveleme, dışarıdan zorunlu kılınan belgelerin aslında bazı meşru avantajlara sahip olabileceği gerçeğini göz ardı etmektedir.


Doxygen ingilizce çıktı mı, yoksa yalnızca ingilizce yazılmış doc dize biçimlendirir mi?
14'te

3
@dcorking Sonuncusu, her şeyi kodun statik yapısına göre düzenlemeye çalışmasına ve mümkün olan her yerde otomatik köprüler sağlamaya çalışmasına rağmen (ve bunlar sıklıkla yanlıştır).
Kyle Strand

2
Aslında, ikisi de. doxygen, kodu ve doxygen yorumlarını ayrıştırır. Sınıf isimleri, üst sınıf isimleri, veri üyesi isimleri, fonksiyon isimleri, argüman tipleri ve isimleri, dönüş tipi: Bunların tümü ayrıştırılmış koddan gelir. Bu ne anlama geliyor doxygen yorumlardan geliyor. Doxygen, doxygen yorumunda \ param olarak belirtilen bir öğe argüman değilse şikayet eder ve belgesiz maddelerden şikayetçi olabilir. Bu minimum kontrollerden başka, yorum vs kod uyuşmazlığı sorunu hala bir olasılık. Dedi ki, doxygen seviyorum. Bir API'yi elle yazmaktan çok daha iyidir.
David Hammen

@DavidHammen de Doxygen, "Metin seçimi değişti Riches" gibi cümleler oluşturur. (Uzun yıllar boyunca kullanmadım ve bu eski versiyonlar hatırladığım İngilizceyi
üretmedi

@ dcorking _ Ne demek istediğin hakkında en ufak bir fikrim yok. Doxygen programcının aklını okuyamıyor. Doxygen'in neler yapabileceğinin güzel bir örneği için , oldukça popüler bir C ++ bilimsel hesaplama paketi olan Eigen için bu üst düzey sayfaya bakın . El yordami ile aramak, bakinmak! Belli ki insanlar tarafından yazılmış, bazıları tamamen otomatik olarak üretilmiş, bazıları ise insan tarafından yazılmış ve otomatik olarak üretilmiş bir belgedir. Söylenirse, doxygen otomatik olarak fan girişi (bu işleve başvuran) ve fan çıkışı (bu işlev ne yapar) üretecektir.
David Hammen

7

Elbette, otomatik belgeler, kod yazarları tarafından yazılan anlayışlı, uygun açıklamaları çoğaltabildiğinde özellikle yararlıdır. Aksi takdirde, sadece yüceltilmiş bir otomatik formatlayıcıdır.

Ancak biçimlendirme işe yaramaz değil. Bir bakışta bir largish bileşenin kamusal yöntemlerini bulabilmenin, sınıflandırmanın ve tamamlamanın garanti edilmesinin değeri vardır. Bir frobnickmutasyonere ihtiyacınız varsa ve o orada değilse, kaynak kodunda gezinmeden orada olmadığını biliyorsunuz . (Olumsuz sonuçların da değeri vardır: bir şey yapmanız gerektiğini biliyorsunuz ve bunu yapmak için daha fazla zamanınız var, çünkü beklemeniz gerekmedi.)

Yani, evet, otomatik belge oluşturma biraz değer katar . Elbette yöneticilerin tahmin ettiği kadar değil ve genellikle iyi bir kopya editörünün yapacağı kadar değil, hiçbir şey yapmıyor.


4
"Kaynak koduyla gezinme" hakkındaki yorumunuzu anlamıyorum. Elbette, her iki durumda da, 'frobnick mutator' veya 'frobnickmutator' gibi bir şey ararsınız ... otomatik olarak üretilen belgeler nasıl yardımcı olur?
Jez,

2
@Jez Mutantlar hakkında frobnickbilmesi gereken herkes bir yazılım devi olmayacak; kaynak koduna nasıl bakacaklarını anlayamayabilirler ( grep/ cscope/ ack/ etc ile aşina olmalarını gerektirebilir ) ve doğru dosyayı bulsalar bile, gerçek kaynak kodunu iyi yorumlanmış olsa bile okunması kolay bulmayabilirler SW perspektifinden. Bir dizine göz atma veya bir arama çubuğuna yazıp ardından bir web sayfasının parçası gibi görünen metne göz atma yeteneği oldukça değerli olabilir.
Kyle Strand

4
@Jez, Programcı olmayanlar veya en azından uzman olmayan kişiler için okunabilir bir belge gereksiz değildir. Gereklidir. Açıkça kod ne ifade etmek amaçlanmıştır yapmak. Herhangi bir kod yazılmadan önce yakalanması gerekir. Ve sorun (lar) ın bilgisi ve çözüm (ler) büyüdükçe güncellenir. Alıntılanan örnekler saklanmaya değmez, ama 'hepsi kaynak kodunda' bebeği banyo suyuyla atmaktır. "Otomasyon oluşturma" kulağa kötü geliyor, "doküman yok, sadece kaynağı oku" daha kötü. Birine sorduğunuzda, "Bu ne işe yarıyor?" ve derler ki, "Hmm, koşup öğrenelim!"
Bill IV

6

Bu formda işe yaramaz olmaktan daha kötüdür, ancak yalnızca halka açık olan imzayı kullandığı için (Javadoc için zaten API belgesini okuyan herkes tarafından görülebilir).

Ancak, yöntemin gövdesini de göz önünde bulunduran otomatik dokümantasyon araçları yazmak mümkündür. Kavramın bir kanıtı olarak, belgelenmiş yöntemden Javadoc'a çağrılan diğer yöntemlerin bir listesini ekleyen küçük bir Eclipse eklentisi yazdım. (Elbette ki her çağrıda değil, örneğin paketine göre filtreler tanımlayabilirsiniz.)

Ve zihinsel olarak tamamen yabancı bir kod üssü çıkarırken oldukça kullanışlı buldum. Verilmiş, çok sınırlı bir kullanım durumu ama kesinlikle bir yardımdı.

Bu deneyime dayanarak, sorunun cevabı şudur: evet, ama daha akıllı araçlara ihtiyacımız var.

Güncelleme: Elbette ek bir soru (herhangi bir dokümantasyon yazmadan önce sorulması gereken) hedef kitlenin kim olduğudır. Bu API'nin müşterileri için herkese açık bir API belgeleniyorsak, tüm bu uygulama ayrıntılarını eklemek Javadoc'a koyduğunuz herhangi bir şey için büyük bir hayırdır, teknik olarak API'nin bir parçasıdır.

Ancak, hedef kitle aynı ürün üzerinde çalışan diğer geliştiriciler ise, belirli bir alanı değiştiren veya okuyan yöntemler gibi uygulama ayrıntılarına otomatik olarak bilgi eklemek hem kabul edilebilir hem de oldukça yararlıdır.


6

Diğer ortamlar hakkında bilgim yok ama konu büyük olduğunda (genellikle açık kaynak kodlu) başkalarının yazdığı PHP projeleriyse, phpXRef mutlak bir hayat kurtarıcı (özellikle de dokümanı çevrimiçi yerleştirir ve Google endeksleyebilirse).

En kötü şekilde yorumlanmış bir proje bile, en azından olayların nerede tanımlandıklarını ve nerede kullanıldıklarını (örneğin yeniden yapılanma yapılırken) bulmama yardımcı olabilir.

İyi yorum yapıldığında, sonuçta elde edilen sayfalar kod temeli için mükemmel bir İncil'e yakın oluşturur (yine de kullanımlarım için).

Dahası, tercih ettiğim IDE benim için yorumlamanın yaklaşık% 75'ini yapan yorum bloğunu (eğer yazarsam / ** yazıyorsam) otomatik olarak oluşturacaktır. Yaptığım şeyi diğer insanlara (ve gelecekteki benimle) açıklamak zorunda kalmamdan dolayı, kodlayıcı ömrüm boyunca taahhüt etmekten kaçındığım aptalca şeyler şaşırtıcı. Doktor üreticisi için yorumum bu yöntemden daha büyük olduğunda, bu genellikle yeterli kahve almadığım ve biraz daha sert düşünmek isteyebileceğim anlamına gelir.

Bu kendi kendine aynı yorum blokları, satır içi tamamlama "yardım" metnini de oluşturur; böylece işlev çağrısı yazarken tam olarak ne olduğunu (diğer kodlayıcılar tarafından) görebiliyorum. Bu benim için muazzam bir verimlilik artışıdır (özellikle, diğer bazı yararlı geliştiricilerin "iyilik uğruna X yap / yapmayın") yazdığı ender durumlarda.

Karmaşık (ve genellikle kötü adlandırılmış) PHP projelerinde belirtilen girdi türlerinin ve daha az kullanılan yöntemlerde argüman sırasının belirtilmesinin ne kadar yararlı olduğunu vurgulayamıyorum. Kendi kodumla bile, bir çağda dokunmadığım bir şey için hangi argümanları belirttiğimi her zaman hatırlayamıyorum.

Bir örnekte, tekrarlayan sorunların kaynağının, önceki geliştiricilere kötü yansıyan bir nedenden ötürü, bazı işlevlerin ve hatta sabitlerin çok sayıda yerde tanımlandığı (yani "eğlence" için tutarsızlık derecesiyle) olduğu anlamına geliyordu. . Projeden uzaklaşmanın işareti buydu.

Katılmadan önce başlayan daha büyük projelerde, hangi geliştiricinin (sınıf dosyasını bir ad ve e-posta ile etiketlediklerini varsayarak) sınıfı oluşturduğunu ve doğru geliştiriciyi bulup konuşabilmenin son derece yararlı olduğunu görebiliyorum.

Otomatik görev listeleri - @todo etiketinin kullanılması (kendimi çalıştığım türdeki projelerde yaygın olarak kullanılır), belgelerin daha fazla çalışma gerektiren şeyleri (veya eksik olduğu kabul edilen özellikleri) izleyebileceği anlamına gelir. Yine IDE'm bunun izini sürüyor ve tek başıma dikkatimi ilk önce neye dikkat etmesi gerektiği konusunda iyi bir rehber olarak görüyor.

Son olarak (ve benim için çok önemli) bazılarının (çok okunan) kodlayıcıların değişiklik yaptığı ve dokümantasyon görevlileri ile konuşmadığı zaman güncel tutmaya çalıştığı önemsiz olmayan yükü kaldırır.

Yani, nedenleri şunlardır:

  • Daha sonraki geliştiricilere zaman kazandırmak,
  • Nerede fonksiyonların çağrıldığını (ve tanımlanır) takip etmek,
  • Aptal kodlamanın farkına varmak,
  • Bir şeylerin eksik olduğu zaman (bir başkasının işaret ettiği gibi) bulmak,
  • Yeniden yapılandırmayı basitleştirme (asla eğlenceli değil)
  • (Pek çok durumda) geliştiricinin ne yapmaya çalıştığı hakkında bir fikir edinmek (bazı notlar bıraktığını varsayarak).
  • Proje birden fazla lisansın devam etmesi için yeterince karmaşıksa (eğlenceli değil) Hangi lisansların belirli bir bölüm için geçerli olduğunu hızla görebilirim. Kuşkusuz, bu bir yan bonus.
  • Proje dosyası hakkında kiminle konuşacağınız hakkında bir fikir edinmek
  • Otomatik görev listeleri

Ayrıca sivri saçlı patronları bir düğmeye dokunarak mutlu etmenin değerini küçümsemeyin.

Kısacası "otomatik dokümantasyon yorumları" kodlama alışkanlıklarım için hayati öneme sahip. Bunun eksik olduğunu düşünen pek çok kişi olduğundan eminim ama tam olarak ne dediğimi bilen adil bir kaç insan olduğundan da eminim. PhpXRef'i (ve en sevdiğim IDE'yi) keşfetmeden önce nasıl hayatta kaldığımı bilmiyorum.


4

Daha sonra gerçek geliştiriciler tarafından gözden geçirilecek olan kazan plakası veya “stand-in” yorumları oluşturmak için dokümantasyon jeneratörlerini kullanmak genellikle iyidir. Eclipse'in auto-JavaDoc işlevini sık sık parametre türleri ve önceden doldurulmuş değerlerle başlık yorumunu oluşturmak için kullanıyorum, sonra sadece belgelerin "et" lerini ekleyin.


3

Bir C # geliştiricisi olarak, tüm sınıflar, yöntemler vb. İçin yorumları zorunlu kılan Stylecop kullanıyorum. Bu yorumları bir araç kullanarak otomatik olarak oluşturuyorum. Çoğu zaman, araç tarafından oluşturulan yorumlar yeterlidir ve nesnenin adıyla çıkarılabilir, örneğin bir Person sınıfı ve kimliği alanı.

Ancak belirgin olmayan bir yöntemi daha fazla yorumlamak istersem, kazan plakası belgesini genişletmek ve ne yaptığı hakkında birkaç açıklama yapmak çok kolaydır. Örnek olarak: Person sınıfımda FirstName + Soyadı'nı döndüren bir yöntem var, ancak ikisinden biri eksik olduğunda neler olup bittiği hakkında biraz doktora ekledim.

Kısacası: Jeneratör tarafından sağlanan metni hiçbir zaman değiştirmezseniz, kazan plakası belgesinin zararlı olabileceğini düşünüyorum. Bu durumda, sadece çizgi gürültüsüdür. Ancak bunları şablon olarak görürseniz, kendiniz veya tüketicileriniz için iyi ve faydalı yorumlar sağlamak için çıtayı düşürürler. Yorumları otomatik olarak oluşturmadan yazabilir misiniz? Tabii, ancak (C # durumunda oldukça ayrıntılı ve elle oluşturmak can sıkıcı) formatına uymak zorunda kalacaksınız ve bu yorumu gerçekten yapma şansınızı düşürecektir.


Yine de bu Stylecop kuralı devre dışı bırakılabilir. Yanılmıyorsam SA1600 Kural.
Jez

@Jez Evet, ama buna karşı karar verdim. Gereksiz yorumlara yol açıyor, ama aynı zamanda gerekli yorumları yazmamı da destekliyor. Mükemmel değil, ama nedir? Devre dışı bıraktığım, görünüşe göre temel BT kelimelerini bile bilmeyen yazım denetimiydi
Christian Sauer

3

Tautology kaçının

Eğer kod belgelerine her türlü gerektiğinde sadece zaman açıklamaktır neden bir yöntem / fonksiyon şey yapıyor, isim için yeterli olacaktır neyi o yapıyor.

Aptalca olmayan bir şey yapıyorsanız veya en az şaşkınlık ilkesini ihlal ediyorsanız, belgeler gereklidir.

Bilginin çıktısı için yalnızca bir biçimlendirici olan otomatik olarak oluşturulan belgeler, kodunuzun tüketicileri tarafından talep edilmektedir. Javadoc bunu son derece iyi yapıyor.

Her şey manuel olarak belgelenmemelidir

GetXXX / setXXX yöntemleri gibi şeyler açıklayıcı olmalıdır, bu yüzden sadece var olduklarını bildiren otomatik oluşturucu belgeler iyi karşılanacaktır.


2

Kod dokümantasyonu, en azından "otomatik" tür, uygulamayı anlamaya çalışan insanlar için en az kullanılan ortak paydayı temsil eder.

En gelişmiş kullanıcılar otomatik kod dokümantasyonunu beğenmeyeceklerdir. Neye (neyin) söylenmesi gerektiğini söyleyen “hedeflenmiş” belgeleri çok daha fazla isterlerdi.

En az gelişmiş kullanıcılar, bunun tam tersi sebeplerden memnun olmazlar; Yine de anlamıyorlardı.

Otomatik kod belgelerinin en "takdir" kullanıcıları, "az bilgili" tehlikeli bir şey olanlardır. "Belgeleri anlayabilirler veya anlayamazlar (büyük olasılıkla da olsa), ancak kendilerini iyi hissederler" "Bu kitle" yönetsel "türlerin çoğunu içerir. Ana izleyiciniz buysa, otomatik kod dokümantasyonu iyi bir şey olabilir.


0

"Neden dokümanlar oluştur" seçeneğine verilen basit cevap, MSDN’yi göstererek kolayca yanıtlanabilir.

API belgelerinin bulunmadığı herhangi bir kütüphaneyi kullanan bir program yazmaya çalıştığınızı hayal edin. Bu bir kabus olurdu. MSDN, kaynak koddan ve yorumlardan üretilebilen ve geliştiriciler için önemli bir kaynak oluşturabilecek türden dokümanın harika bir örneğidir.

Eğer bir uygulama yazıyorsanız (yani başkaları tarafından tüketilecek bir kütüphane değil), o zaman belki de rahatsız edilmemiş bir durum söz konusudur - fakat o zaman bile, ne kadar büyük, yalnızca dahili bir uygulamada çok sayıda kitaplık yoktur bu arada? Böyle bir takıma katıldığınızda, göz atılabilir API dokümanlarına sahip olmak yardımcı olacaktır.

Hiçbir araç belgelerinizi sizin için yazmayacak, ancak size yine de elle yazmak zorunda olduğunuz kazanı veriyorlar, bazı araçlar (doxygen gibi) ayrıca diyagramlar ve referans listeleri de (örneğin, çağrılan ve çağıran işlevler) oluşturacaktır. kaynak koduna bakarak bile kolayca keşfedilmez.

Belli ki pragmatik sağduyu, belgelendirilen şeye uygulanmalı, özellikler ve küçük işlevler göz ardı edilebilsin (ve araçlarda bile kuşaktan atlandı); .

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.