/// yorum blokları neden önemlidir?

Birisi bir keresinde tüm yöntemlerimizi /// <summary>yorum blokları (C #) ile belirtmemiz gerektiğini söyledi, ancak bunun nedenini açıklamadı.

Onları kullanmaya başladım ve beni biraz rahatsız ettiklerini gördüm, bu yüzden kütüphaneler ve statik yöntemler dışında onları kullanmayı bıraktım. Hacimlidirler ve onları güncellemeyi her zaman unutuyorum.

/// <summary>Kodunuzda yorum blokları kullanmak için iyi bir neden var mı ?

Normalde //yorumları hep kullanırım , sadece /// <summary>merak ettiğim bloklar.

Onları mümkün olduğunca kullanın.

Evet, bunlar yöntemin belgeleri haline gelen özel yorumlar. Üretilen <summary>parametre etiketleri, vb . İçerikleri, siz veya bir başkası yönteminizi çağırmaya hazırlanırken intellisense içinde gösterilir. Esas olarak, ne yaptığını anlamak için dosyaya gitmek zorunda kalmadan (ya da sadece yöntem imzasını okumaya çalışın ve en iyisini umuyoruz), yöntem ya da sınıfınızın tüm belgelerini görebilirler.

Evet, bunları saklamak istediğiniz veya paylaşılabilecek bir şey için kesinlikle kullanın.

Ayrıca bunları Sandcastle ve XML çıktısını alan ve güzel, MSDN tarzı belgelere dönüştüren Sandcastle Yardım Dosyası Oluşturucu ile birlikte kullanın .

Çalıştığım son yer, her gece belgeleri yeniden oluşturduk ve iç ana sayfa olarak barındırdık. Şirketin ilkleri MF idi, bu yüzden MFDN idi;)

Normalde sadece kolayca paylaşılan bir .chm dosyası oluşturduğum halde.

MSDN biçiminde görmeye başladığınızda, her şeyi belgelendirmeye ne kadar bağımlı olduğunuza şaşırırsınız!

Kodlama standartlarınız bu tür yorumları (ve bir API veya çerçeve için bir kodlama standardı kullanmanızı gerektiriyorsa) talep ediyorsa, başka seçeneğiniz yoktur, bu tür yorumları kullanmanız gerekir.

Aksi takdirde, bu yorumları kullanmayacağınızı ciddiye alın. Kodunuzu bu şekilde değiştirerek çoğu durumda bunlardan kaçınabilirsiniz:

    /// <summary>
    /// Checks if a user is authorized to access the resource
    /// </summary>
    public bool SecurityCheck( User user ) {

    }

için

    /// <summary>
    /// Checks if a user is authorized to access the resource
    /// </summary>
    public bool IsAuthorizedToAccessResource( User user ) {

    }

için

    public bool IsAuthorizedToAccessResource( User user ) {

    }

Sınıfınız, yönteminiz ve mülk isminiz açık bir şekilde anlaşılmalıdır, bu nedenle eğer bunlara ihtiyacınız varsa, muhtemelen bir koku.

Ancak, bunları bir API, kütüphane vb. Genel sınıflarda, yöntemlerde ve özelliklerde kullanmanızı öneririm. onları yazmak için.

Ama yine de dilimleyin, koruyun veya silin.

Geri dönüp yeni kodla uyuşacak şekilde yorumlarınızı düzenlemeye devam etmeniz gerektiğine karar verirseniz, en başta bunları yanlış yapıyor olabilirsiniz. Özet elemanı tam olarak şunu içermelidir - özet - özetlediğiniz şeyin neyi ve nedenini .

Nitelendiren nasıl bir şey yorumların çalışır KURU ihlal eder. Eğer kodunuz yeterince açıklayıcı değilse, belki geri dönüp yeniden yönlendirmelisiniz.

Evet, onları ben yarattım. [sıfırdan yeni sistemler inşa ederken]

Hayır, onlardan hiç faydalanmadım. [bakım gerektiren mevcut sistemler üzerinde çalışırken]

"Özet" yorumlarının sonunda kodla senkronize etme eğiliminde olduğunu buldum. Ve birkaç kötü davranış yorumunu fark ettiğimde, o projeyle ilgili tüm yorumlara olan inancımı kaybetme eğilimindeyim - hangilerine güveneceğinden asla emin olamazsınız.

Bir şeyi yapmayı unutmak kötü bir fikir değildir. Herhangi bir belgeyi güncellemeyi unutmak. Bunları programlamamda çok faydalı buldum ve kodumu devralan insanlar onlara sahip oldukları için müteşekkiriz.

Kodunuzu belgelemek için en görünür yollardan biridir.

Satır içi belgeleri okumak için kaynak kodunu bulmak ya da hangi kodun yapıldığı üzerine bir belge kazmak zorunda kalmak acı vericidir. Eğer istihbarat sayesinde işe yarar bir şey bulabilirseniz, insanlar sizi sevecektir.

" Benim gibi çok kullanılması gerekiyor;) "

Eskiden yorumlarla oynardım (///). Bir sınıf için sadece böyle bir yorum yapabilirsiniz

namespace test
{
    /// <summary>
    /// Summary description for Calendar.
    /// </summary>
    public partial class DatePicker : System.Web.UI.Page
    {

Ancak, bir yöntem için daha fazla parametre ve dönüş tipleri için açıklama vererek ekleyebilirsiniz.

/// <summary>
/// Assign selected cases to the participating users based on the filters and configurations
/// </summary>
/// <param name="noOfParticipants">No. of participants to the Table</param>
/// <param name="value">Value of the participant</param>
/// <returns>No Of Cases Assigned on successfull completion</returns>
public long AssignCasesToParticipatingUsers(int noOfParticipants,string value)
{

Bu yorumu oluşturmak için bir kısayol kullanabilirsiniz (///+Tab).

onları kütüphaneler dışında kullanmak

Yararlı oldukları zaman budur. XML Dokümantasyonu ile nesil açık ve meclise bir referans, projesi olmadan, intellisense daha ayrıntılı gösterecektir.

Ancak mevcut projenin iç kısımları için sadece yoluna devam ediyorlar.

Onları kullanıyorum, ancak bazılarının evrensel olarak dediği gibi. Küçük yöntemler için, açıkladıkları koddan kolayca daha büyük olabilirler. Bunlar, sistemde yeni insanlara verilebilecek belgeleri oluştururken, öğrenirken başvuracakları bir şeyleri olması için faydalıdır. Her ne kadar, programcılar olarak genellikle bazı kodların ne olduğunu öğrenebiliriz, çünkü bize yol gösterecek ve koltuk değneği olarak hareket edecek yorumların olması güzel. O Eğer sahip kodunda bir yerde daha sonra yazılmak üzere (yüzen bazı Word belgesi daha muhtemel) o güncel bilgileri edinmek için en muhtemel yerdir.

VB'de eşdeğerini kullanıyorum (çünkü C # kullanmama izin vermiyorlar - görünüşe göre çok zor ... yorum yok.) Onları çok uygun buluyorum. Çoğu zaman, sadece yorumları değiştirmek zorunda kalmaktan (veya "senkronize edilmemek") önlemek için, yerleştirmeden önce prosedür veya fonksiyonun tamamlanmasını beklerim.

Ben mutlaka bir roman yazmam - sadece temeller, parametre tanımı ve bazı açıklamalar (genellikle orada "sıradan bir şey" olup bittiği zaman - geçici bir çözüm veya orada olmamayı tercih ettiğim başka bir saçmalık olduğunda) "şimdilik" seçeneğim yok.) (Evet, biliyorum, "şimdilik" bu yıllar sürebilir.)

Ben uncommented kod tarafından ciddi tahriş. Bir danışman, bileşenlerimizden birinin ilk versiyonunu yazdı ve hiçbir şey yorum yapmadı ve burada seçtiği isimler tercih edildi. Bir yıldan fazla bir süredir gitti ve biz hala eşyalarını sıralıyoruz (kendi eşyalarımız üzerinde çalışmaya ek olarak).