it-swarm.asia

Başlık dosyasındaki veya kaynak dosyadaki işlevleri belgelemek daha mı iyi?

"Kaynak" ve "başlık" dosyası (çoğunlukla C ve C++) arasında ayrım yapan dillerde, başlık dosyasındaki işlevleri belgelemek daha iyidir:

( CCAN )

/**
 * time_now - return the current time
 *
 * Example:
 *  printf("Now is %lu seconds since Epoch\n", (long)time_now().tv_sec);
 */
struct timeval time_now(void);

veya kaynak dosyada?

(PostgreSQL'den çalınmış)

/*
 * Convert a UTF-8 character to a Unicode code point.
 * This is a one-character version of pg_utf2wchar_with_len.
 *
 * No error checks here, c must point to a long-enough string.
 */
pg_wchar
utf8_to_unicode(const unsigned char *c)
{
...

Yalnızca başlıkta, yapılar, makrolar ve static inline fonksiyonları. Sadece başlık dosyasında bildirilen ve tanımlı bir kaynak dosyada.

İşte aklıma gelen bazı argümanlar. Kaynak dosyada belgelemeye doğru eğildim, bu yüzden "Pro-header" argümanlarım biraz zayıf olabilir.

Pro-başlık:

  • Kullanıcının belgeleri görmek için kaynak koduna ihtiyacı yoktur.
    • Kaynak, elverişsiz, hatta imkansız olabilir.
    • Bu, arayüz ve uygulamayı daha da ayrı tutar.

Pro-source:

  • Başlığı çok daha kısa hale getirir ve okuyucuya modülün bir bütünüyle kuşbakışı bir görünümünü verir.
  • Bir işlevin dokümantasyonunu uygulamasıyla eşleştirir, bir fonksiyonun söylediklerini yaptığını görmeyi kolaylaştırır.

Yanıt verirken, lütfen hangi araçların ve "modern IDE'lerin" yapabileceğine dayanan argümanlara dikkat edin. Örnekler:

  • Uzman başlığı: Kod katlama, yorumları gizleyerek yorum yapılan başlıkları daha gezinilebilir hale getirmeye yardımcı olabilir.
  • Profesyonel kaynak: cscope 's Find this global definition özelliği sizi başlık dosyasından ( kaynak dosyaya ((== --- ==) tanımının olduğu) ( beyanı ).

Söylemiyorum, böyle argümanlar yapma, ama herkesin kullandığınız araçlarla sizin kadar rahat olmadığını unutmayın.

94
Joey Adams

Benim görüşüm...

  • Başlık dosyasında işlevin nasıl kullanılacağını ya da bildirime daha doğru bir şekilde nasıl yaklaştığını belgeleyin.

  • Kaynak dosyada işlevin nasıl çalıştığını (koddan açıkça görülmüyorsa) veya daha doğru bir şekilde, tanıma yakın bir yere yazın.

Başlıktaki kuşbakışı şey için, kapatılması gereken belgelere ihtiyacınız yoktur - beyan gruplarını bir kerede belgeleyebilirsiniz.

Genel olarak, arayan kişi hatalar ve istisnalar ile ilgilenmelidir (eğer sadece soyutlama katmanları aracılığıyla yayıldıkça çevrilebiliyorsa), bunlar ilgili beyanlara yakın olarak belgelenmelidir.

101
Steve314

Doxygen (ilk örnekte not, /** İle başladığı için gerçekten bir Doxygen yorumu gibi görünüyor) gibi bir araç kullanacaksanız, o zaman gerçekten matter - Doxygen başlığınızı ve kaynak dosyalarınızı inceleyecek ve dokümantasyonu oluşturmak için tüm yorumları bulacaktır.

Ancak, açıklamaların bulunduğu başlıklara dokümantasyon yorumlarını koymaya daha meyilli olurum. Müşterileriniz yazılımınızla arabirim oluşturmak için üstbilgilerle ilgilenecek, üstbilgiler kendi kaynak dosyalarına ekleyecekleri şeydir ve API'nizin neye benzediğini görmek için ilk önce burada olacaklardır.

Örneğin çoğu Linux kütüphanesine bakarsanız, Linux paket yönetim sisteminizde genellikle sadece kütüphanenin ikili dosyalarını içeren bir paket bulunur (kütüphaneye ihtiyaç duyan programlara sahip "normal" kullanıcılar için) ve kitaplığın başlıklarını içerir. Kaynak kodu normalde doğrudan bir pakette sağlanmaz. API'nın belgelerini almak için bir yerde bir kütüphanenin kaynak kodunu almak zorunda kalırsanız gerçekten hantal olur.

35
Jesper

Bu sorunu (yaklaşık 25 yıl önce) kaynak dosyada kullanılabilen ve bir awk komut dosyası (dehşet) tarafından taranan bir grup # tanım (örneğin <nothing> olarak çözülen genel, özel vb.) Oluşturarak çözdük. !) .h dosyalarını otomatik olarak oluşturmak için. Bu, tüm yorumların kaynakta yaşadığı ve (uygun olduğunda) oluşturulan .h dosyasına kopyalandığı anlamına gelir. Oldukça Eski Okul olduğunu biliyorum, ancak bu tür satır içi belgeleri büyük ölçüde basitleştirdi.

12
Peter Rowell

Bunun daha büyük bir proje içindeki kod olduğunu varsayarsak (geliştiricilerin kaynak ve başlıklar arasında sık sık hareket edecekleri) ve bunu sağlar değil Başkalarının kaynağa erişemeyebileceği bir kütüphane/orta eşya, bunun en iyi şekilde çalıştığını buldum ...

  • Başlıkları:
    1-2 satırlık yorumları, yalnızca ihtiyaç duyuldukları takdirde kısaltın.
    Bazen bir grup ilgili işlevin üstündeki yorumlar da faydalı olabilir.
  • Kaynak:
    Doğrudan işlevin üstündeki API ile ilgili dokümanlar (isterseniz düz metin veya doxygen) .
  • Yalnızca işlevin gövdesindeki kodu değiştiren bir geliştiriciyle ilgili uygulama ayrıntılarını saklayın.

Bunun ana nedeni yorumları koda yakın tutmaktır, başlıklarda dokümanlar daha sık kod değişiklikleri ile senkronizasyon kurtulmak eğiliminde olduğunu fark ettim (tabii ki onlar gerekir ' t, ama en azından projemizde yaptılar) . Ayrıca geliştiriciler, başlıkta dokümanlar olsa bile, bazı değişiklikler yaptıklarında işlevlerin en üstüne belge ekleyebilirler, bu da çifte ikiye veya yararlı bilgilerin yalnızca doc dizelerinden birinde olmasına neden olabilir.

Tabii ki bir kongre seçebilir ve tüm geliştiricilerin takip etmesini sağlayabilirsiniz, konvansiyonu en çok doğal uyumun üstünde buldum ve bakımı en az sorun yaratıyor.


Her şeyden önce, büyük projeler için - başkaları sürüm denetimini güncellediğinde potansiyel olarak 100'lerin veya 1000'lerin dosyalarının yeniden derlenmesine neden olacağını bildiğinizde bir başlıkta küçük düzeltmeler yapmak için bir eğim değil vardır - ikiye ayırma hatalarını da yavaşlatmak.

9
ideasman42

Yorumlar dokümantasyon değildir. Bir işlevin belgeleri genellikle 2K metin, muhtemelen diyagramlarla birlikte olabilir - örneğin, Windows SDK'daki işlevlerin belgelerine bakın. Dokümanınıza yorumunuz böyle bir şeye izin verse bile, yorumu içeren kodu okunamaz hale getireceksiniz. Doküman üretmek istiyorsanız, bir kelime işlemci kullanın.

6
Neil Butterworth

(Oldukça sınırlı ve önyargılı) düşünceme göre, kaynak kodlu düşünme biçimim. C++ 'da bitler ve parçalar yaptığımda, genellikle başlık dosyasını bir kez düzenlerim ve sonra ona bakmak için asla geri dönmem.

Belgeleri kaynak dosyaya yerleştirdiğimde, kodları düzenlerken veya okurken her zaman görüyorum. Sanırım bu bir alışkanlık.

Ama bu sadece ben ...

5
MattyD

Kaynak kodunuzun paydaşları (örneğin, küçük bir kütüphane) "kullanıcılar" (uygulamasına dahil olmadan kütüphanenizin işlevselliğini kullanacak geliştiriciler) ve "geliştiriciler" (siz ve kütüphaneyi uygulayacak diğer geliştiriciler) , daha sonra "kullanıcıların bilgilerini" başlığa ve "uygulama notunu" kaynağa koyun.

Başlık dosyalarını kesinlikle gerekli olandan daha fazla değiştirmeme arzusu ile ilgili olarak - kitaplığınızın "çılgın bir değişiklik akışında" olmadığı, "arayüz" ve "işlevliliğin" çok fazla değişmeyeceğini ve hiçbirinin başlık yorumları çok sık değişirse. Öte yandan, kaynak kodu yorumları kaynak kod ile senkronize ("taze") tutulmalıdır.

4
rwong

Doxygen kullanmanın asıl amacı, oluşturmak dokümantasyon yapmak ve başka bir yerde erişilebilir kılmaktır. Üstbilgilerdeki tüm bu belgeler sadece gerekli çöp beyanını ve belki de aşırı yüklemelerini hızlı bir şekilde tespit etmeyi zorlaştıran çöptür. Bir liner yorumu oraya gitmesi gereken maksimumdur, ancak bu kötü bir uygulamadır. Kaynaktaki belgeleri değiştirirseniz, kaynağı yeniden derleyip yeniden bağlarsınız. Ancak, başlıklara dokümanlar koyarsanız, orada en ufak bir şeyi değiştirmek istemezsiniz, çünkü proje yeniden inşasının önemli bir bölümünü tetikleyecektir.

0
Slava