Bir "kaynak" ve "başlık" dosyası (özellikle C ve C ++) arasında ayrım yapan dillerde, başlık dosyasındaki işlevleri belgelemek daha iyi olur:
/**
* 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 uyarlanmıştır)
/*
* 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)
{
...
Yapılar, makrolar ve static inlineişlevler gibi bazı şeylerin yalnızca başlıkta tanımlandığını unutmayın . Sadece bir başlık dosyasında bildirilen ve bir kaynak dosyada tanımlanan şeylerden bahsediyorum .
İşte aklıma gelen bazı argümanlar. Kaynak dosyada belgelemeye yaslanıyorum, bu yüzden "Pro-header" argümanlarım biraz zayıf olabilir.
Pro-başlık:
- Kullanıcı belgeleri görmek için kaynak koduna ihtiyaç duymaz.
- Kaynak elde etmek için uygun olmayabilir veya hatta imkansız olabilir.
- Bu, arayüzü ve uygulamayı ayrı tutar.
Pro-source:
- Başlığı çok daha kısaltır ve okuyucuya modülün bütününe kuş bakışı bir görünüm kazandırır.
- Bir işlevin belgelenmesini, uygulamasıyla eşleştirir ve işlevin yaptığı şeyi yaptığını görmesini kolaylaştırır.
Cevap verirken, lütfen hangi araçların ve "modern IDE'lerin" yapabileceklerine dayanarak tartışmalara karşı dikkatli olun. Örnekler:
- Pro-header: Kod katlama, yorumları gizleyerek yorumlanmış başlıkların daha gezinilebilir olmasına yardımcı olabilir.
- Pro-source: cscope 'ın
Find this global definitionözelliği (kaynak dosyasının götüren tanımı ise) yerine (başlık dosyası beyanı olduğunu).
Bu tür tartışmalar yapma demiyorum, ama herkesin sizin kullandığınız araçlarla olduğu kadar rahat olmadığını unutmayın.