Kod belgeleri: Herkese açık mı Herkese açık değil mi?

Yazılan kodun açıklayıcı olması ve bir kitap gibi okunması gereken zihniyete sahip geliştiricilerden biriyim.

Ancak, diğer kişilerin kullanması için kütüphane kodu geliştirirken, başlık dosyalarına mümkün olduğunca fazla belge koymaya çalışıyorum; hangisi şu soruyu gündeme getiriyor: Kamuya açık olmayan dokümantasyon yöntemleri zaman ayırmaya değer mi? Onları doğrudan kullanmayacaklar, aslında kullanamıyorlar. Aynı zamanda ham kodu (isteksiz de olsa) dağıtırsam, bu Kamusal olmayan yöntemler görünür olacak ve açıklanması gerekebilir.

Sadece seyahatlerinizde gördüğünüz veya kullandığınız bazı standart ve uygulamaları aramak.

Ben sadece bir "son kullanıcı" onları kullanmayacak çünkü iç için belgeleri atlamayı düşünün olmaz; kod bakımı, tüm bileşenler için, özellikle de özellikle en karmaşık (ve çoğu zaman değişen) parça olma eğiliminde olan dahili belgeler için dokümantasyon yorumlarını dahil etmek için fazlasıyla yeterli sebeptir .

Bununla birlikte, soyutlamayı sürdürmek için, bunların başlık dışı kaynak koduyla (kamuya açık olarak belgelenmek yerine) sınırlı tutulmaları için geçerli bir dava olabilir.

Bunların hepsi oldukça öznel, unutmayın.

Tamam, ben de yorum için çeşitli yorumlama / belgeleme yolunu eklemek. Gerekçe, yalnızca başlıkta bildirilen işlevleri veya üye işlevleri açıklamaktan kaçınmaktır. Bir yandan başlığa çok fazla gürültü katmaktan korkuyorum. Diğer yandan, tanım ile birlikte dokümantasyon, bakımcının uyması için daha kolaydır. Doxygen her iki şekilde de ilgilenmez ve gerektiğinde ayrıcalıkları filtreleyebilir.

Sınıf başlığında:

• dahil başlıklar (neden)
• sınıf tanımları her zaman (amaç ve sorumluluklar)
• her zaman saf sanal işlevler (tam sözleşme)
• kendi kendini açıklayan alıcılar olmadıkça satır içi işlevler
• açıklayıcı olmadıkça beyan edilen diğer türler
• statik veri üyeleri (neden)
• açıklayıcı olmadıkça diğer veri üyeleri
• varsa makrolar (sözleşme ve neden)

Sınıf içi uygulama kodu:

• yerel bildirimler başlıktaki gibi
• her zaman işlev tanımları (tam sözleşme)
• üye işlev tanımları her zaman (tam sözleşme veya sanal geçersiz kılmanın köküne başvuru)
• Varsa statik değişkenler tanımlandı (amaç neden)

Şablon başlığında:

• yukarıdaki birleşti ve
• şablon argümanları için uygun / uygun olmayan türler ve
• statik olarak ne kadar iyi tespit edilir

private:Özel bölümün başında kullanıcıların gerektiğinde tüm belgeler olduğunu.

Belgeler buna değecek herhangi bir gün, kullanım örneklerini ve hikayelerini kısa bir şekilde açıklamaya yardımcı olur. Kodun ne kadar açıklayıcı olduğu, işi birkaç hikaye anlatımı kadar kolay açıklayamaz. Kod kesinlikle neler olduğunu anlamak için kullanıcının mantık yoluyla takip gerektirir. :-) 2 sentim ...

Kesinlikle!

Bu kodun kendini belgelemesi gereken yaşamak için bir slogan. Yine de, özel kodun genel koddan daha fazla olmasa da, daha fazla belgeye ihtiyaç duyduğunu söyleyecek kadar ileri gideceğim, çünkü genellikle burada en varsayımlar genellikle kodlayıcıların karanlıkta kalacağını varsaydığı için gerçekleşir . Yani, birkaç ay sonra, bir hata yolunuza geldiğinde, kodun (belki de kendiniz) arkasındaki fikrin ne olduğunu yazmaya çalışarak zaman harcayacaksınız.

Belgeler başkalarına güzel bir hediye olarak bulunmamalıdır. Belgeler, tüm yüzlerinde (iyi seçilmiş değişken isimleri, kendi kendini belgeleyen sınıf isimleri, iyi organize edilmiş kod, uygun şekilde segmentlere ayrılmış yöntemler, vb.) Kodunuzla temasa geçebilen herkese bir armağandır.