Sınıf dokümanları başlığına ne eklemeliyim

Varlık, İş Mantık ve Veri Erişimi sınıflarım için bilgilendirici sınıf dokümantasyon formatı arıyorum.

Buradan aşağıdaki iki biçimi buldum

Biçim 1

///-----------------------------------------------------------------
///   Namespace:      <Class Namespace>
///   Class:          <Class Name>
///   Description:    <Description>
///   Author:         <Author>                    Date: <DateTime>
///   Notes:          <Notes>
///   Revision History:
///   Name:           Date:        Description:
///-----------------------------------------------------------------

Biçim 2

// ===============================
// AUTHOR     :
// CREATE DATE     :
// PURPOSE     :
// SPECIAL NOTES:
// ===============================
// Change History:
//
//==================================

Aşağıdaki temel unsurları hissediyorum

• Yazar
• Oluşturma Tarihi
• Açıklama
• Revizyon Geçmişi

Ad Alanı ve Sınıf adı zaten orada olacak.

Lütfen düşüncelerinizi, hangi biçimin önerildiğini ve düzeltme geçmişi yazmanın standart bir yolu olup olmadığını bana bildirin.

Orada önerdiğiniz bilgilerin çoğu kaynak veri havuzunda bulunur.

Gerçekten ihtiyacınız olan tek şey, sınıfın orada ne olduğunu söyleyen amaç bölümüdür.

Diğer bilgileri her bilmek istediğinizde depoya bakmak yorucu olur mu? Hayır derdim. Orijinal yazarın kim olduğunu umursuyorsunuz? Ya da dosya ilk oluşturulduğunda? Eklentiler (Visual Studio için Ankh SVN gibi) genellikle geçerli dosyanızın içinde sağ tıklamanıza ve dosyanın kayıt günlüğünü görüntülemenize izin verir, bu nedenle bu bilgileri gerçekten görmek çok zor değildir.

Ayrıca, sürüm geçmişini bir yorumda depolarsanız, bu yorumun korunması gerekir. Yani zamanla size yalan söyleme şansı var. Kaynak kodu deposu bu geçmiş verileri otomatik olarak tutar, bu nedenle bu bakıma ihtiyaç duymaz ve doğru olur.

Açıklayıcı sınıf, yöntem ve değişken adlarına sahip olun . Bu, amaç ve açıklama gibi yorumlara olan ihtiyacı ortadan kaldıracaktır. Bazen yöntem ne kadar kısaysa o kadar iyi olur. Aksine, amacını açıkça tanımladığı sürece bir yöntem adı istediğiniz kadar yapın. Sadece kesinlikle hayati önem taşıyan ve belirli bir şekilde kod anlaşılmasına yardımcı olan notlara sahip olun. Kodda değişiklik yaparken, programcılar genellikle yorumları güncellemeyi unutur. Yorumların ve kodun senkronize olmaması ve faydadan çok zarar vermesi ile sonuçlanabilir.

Jeff Atwood - Yorum Yapmadan Kodlama'nın bu makalesini okuyun .

Doküman oluşturmak için standart etiketler kullanıyorum. Ne fazla ne eksik. Buraya bakın

Sınıfa ait olmayan hiçbir zaman bilgi koymuyorum. Yazar, veriler, düzeltmeler Sürüm Kontrol Sisteminde depolanacak verilerdir.

Sunulan iki biçim belge oluşturmak için işe yaramaz ve yorumlarda en büyük hataya sahiptir, düzeltme geçmişini listeler.

Bu bilgilerin çoğu, kaynak kontrol deponuz tarafından eklenebilir ve sizi yalnızca sınıfın kapsamını ve davranışını doğru bir şekilde tanımlaması gereken açıklamayla bırakır. Bazı örnek olarak Java JDK için Javadoc bazı göz atın öneririz.

Bu listedeki her şey gereksiz. Kaynak kontrolünüz neredeyse her şeye dikkat etmeli ve kapsamadığı şey iyi adlandırma kuralları ile halledilir.

Sınıfınızın ne yaptığını anlamak için "Açıklama" nızı okumak zorunda kalırsam (a) isminizi kötü adlandırdınız veya (b) çok fazla şey yapan kötü bir sınıf (SRP) yazdınız.

Üstbilgilerimi değiştirerek oynuyordum, çünkü diğerlerinin de belirttiği gibi, bu bilgilerin çoğu depoda bulunabilir ve şu ana kadar saklamak istediğim büyük alanlar şunlardır:

• Açıklama - Kod tarafından neler yapılır.
• Notlar - Kodun kendisindeki yorumlardan kolayca türetilemeyen kod hakkında bilinmesi gereken her şey.
• Referanslar - Kodun bağımlı olduğu includeveya benzer ifadeler kullanılmasına rağmen açıkça belirtilmeyen tüm referanslar .

Eklenmesi yararlı olabilecek bir öğe de Anahtar Kelimeler ile ilgili bir bölümdür. İşlev, sınıf, yapı vb. Adlar için arama yapabilmenize rağmen, dosyadaki diğer adların açıkça belirtmediği bazı anahtar kelimeler olabilir. Ya da daha eski, kötü belgelenmiş kodlar için, bakım için kodun belgelenmesinde ilk adım bu olabilir.

Şimdiye kadar okuduğum diğer cevapların çoğu, her zaman kullanılabilir olan tek bir havuz olduğunu varsaydı

Kaynak kodu depoya olan bağlantıyı kaybedebildiğinden (yani kopyalandıysa) sınıf belgelerim şöyle:

• class documentation header (= dosyanın başındaki yorum bloğu) yalnızca gerekli yasal bilgileri içerir (örn. gpl-lisansı altında xyz telif hakkı)
• sınıfı kullanan bir geliştiricinin bilmesi gereken her şey class-java-doc-comments (veya bunun .net eşdeğeri) içine girmelidir, böylece modern IDE'ler bu bilgiyi sınıfı kullanan araç ipucu bilgi kaynağı kodu olarak gösterebilir.

Ayrıca, hata düzeltme veya özellik isteği için bilet numarasını da ekleyebilirsiniz, böylece sınıfın nerede / ne zaman / neden oluşturulduğuna dair bir ipucu alabilirsiniz (eğer şansınız varsa, birkaç yıl sonra hala biletlere erişebilirsiniz).

Beeing, eski kapalı kaynaklı eski programlardaki sorunları düzeltmek istediğinde, kodun orijinal gereksinimlerini anlamam benim için oldukça değerli olan bilet numaraları.