Birisi bir keresinde tüm yöntemlerimizi
/// <summary> yorum blokları (C #) ama 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 hariç onları kullanmayı bıraktım. Hantal ve her zaman güncellemeyi unutuyorum.
Kullanmak için iyi bir neden var mı
/// <summary> kodunuzdaki yorum blokları?
Normalde
// her zaman yorum yapar, sadece
/// <summary> blok merak ediyordum.
Mümkün olduğunca bunları kullanın.
Evet, bunlar yöntemin belgeleri haline gelen özel yorumlar. Oluşturulan
<summary> İçeriği, parametre etiketleri vb. Sizin veya başka bir kişi yönteminizi çağırmaya hazır olduğunda akıllıca görünür. Esas olarak, ne yaptığını anlamak için dosyanın kendisine gitmeye gerek kalmadan yönteminiz veya sınıfınızla ilgili tüm belgeleri görebilir (veya yalnızca yöntem imzasını okumaya ve en iyisini ummaya çalışmaya).
Evet, kesinlikle saklamak istediğiniz veya paylaşılabilecek herhangi bir şey için kullanın.
Çalıştığım son yer, her gece belgeleri yeniden oluşturduk ve dahili bir ana sayfa olarak ağırladık. Şirketin baş harfleri MF idi, bu yüzden MFDN idi;)
Normalde sadece kolayca paylaşılan bir .chm dosyası üretmeme rağmen.
MSDN biçiminde görmeye başladığınızda her şeyi belgelemeye ne kadar bağımlı olduğunuza şaşıracaksınız!
Kodlama standardınız bu tür yorumları kullanmanızı istiyorsa (ve bir API veya çerçeve için bir kodlama standardı bunu gerektirebilir), başka seçeneğiniz yoktur, bu yorumları kullanmanız gerekir.
Aksi takdirde, bu tür yorumları kullanmamaya özen gösterin. Çoğu durumda kodunuzu şu şekilde değiştirerek 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 adınız açık olmalıdır, bu yüzden bunlara ihtiyacınız varsa, muhtemelen bir koku.
Ancak, bunları bir API, kitaplık vb. Herhangi bir genel sınıf, yöntem ve özelliklerde kullanmanızı öneririm ... En azından, bunu kullanarak herhangi bir geliştiriciye yardımcı olmak için dokümanlar üretecek ve onları yazmak için.
Ama yine de dilimliyorsunuz, bakımını yapıyor veya siliyorsunuz.
Geri dönüp yorumlarınızı yeni koda karşılık gelecek şekilde düzenlemeniz gerektiğini fark ederseniz, ilk etapta bunları yanlış yapıyor olabilirsiniz. Özet öğesi, özetlediğiniz şeyin tam olarak - bir özet - ne ve neden içermelidir.
Yorumlarda nasıl bir şeyin açıklanması DRY'yi ihlal eder. Kodunuz yeterince açıklayıcı değilse, belki geri dönüp refactor olmalısınız.
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]
Ben "Özet" yorum sonunda kodu ile senkronizasyon çıkmak eğiliminde olduğunu buldum. Ve birkaç kötü davranan yorum fark edince, o proje hakkındaki tüm yorumlara olan inancını kaybetme eğilimindeyim - hangilerine güveneceğinden asla emin değilsin.
Bir şey yapmayı unutmak onu kötü bir fikir yapmaz. Herhangi bir belgeyi güncellemeyi unutmak. Bunları programımda çok yararlı buldum ve kodumu devralan insanlar onlara sahip oldukları için minnettarlar.
Kodunuzu belgelemenin en görünür yollarından biridir.
Satır içi belgeleri okumak için kaynak kodunu bulmak ya da kodun ne yaptığını gösteren bir belgeyi kazmak zor. Eğer istihbarat yoluyla faydalı bir şey varsa, insanlar sizi sevecektir.
"Benim gibi Çok Kullanılmalı;)"
Eskiden yorumlarla oynardım (///). Bir sınıf için 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 parametreler ve dönüş türleri için açıklama vererek daha fazlasını 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).
Eşdeğer VB (C # kullanmama izin vermeyecekleri için) kullanıyorum - görünüşe göre çok zor ... yorum yok.) Onları çok uygun buluyorum. Çoğu zaman bekliyorum yalnızca yorumları değiştirmek zorunda kalmamak veya "senkronize olmama" durumunu sağlamak için prosedür veya işlev, bunları koymadan önce hemen hemen tamamlanmıştır.
Mutlaka bir roman yazmıyorum - sadece temel bilgiler, parametre açıklaması ve bazı açıklamalar (genellikle "olağan dışı" bir şey olduğunda orada oluyor - geçici olarak ya da orada olmamak ama sahip olduğum diğer saçmalıklar "şimdilik" seçeneği yok.) (Evet, biliyorum, "şimdilik" bu yıllar sürebilir.)
Uncommented code tarafından ciddi bir şekilde rahatsız oldum. Bir danışman, bileşenlerimizden birinin ilk versiyonunu yazdı ve hiçbir şey yorumlamadı ve isim seçimi burada ve orada istenmeye bırakılıyor. Bir yılı aşkın bir süredir gitti ve hala eşyalarını sıralıyoruz (kendi eşyalarımız üzerinde çalışmaya ek olarak).
kütüphaneler dışında kullanma
İşte faydalı oldukları zaman. XML Belgelendirme oluşturma açık ve Meclisi'ne bir başvuru, projesi olmadan, akıllıca daha fazla ayrıntı gösterecektir.
Ama mevcut projenin içselleri için, sadece yoluna devam ediyorlar.
Onları kullanıyorum ama bazı insanların söylediği gibi evrensel olarak değil. Küçük yöntemler için açıkladıkları koddan daha büyük olabilirler. Bunlar, sistemde yeni olan kişilere verilebilecek belgeleri oluşturmak için çok faydalıdır, böylece öğrenirken başvuracakları bir şeyleri vardır. Programcılar olarak, genellikle bize yol gösterecek ve koltuk değneği gibi davranacak yorumlara sahip olmak için bazı kodların ne olduğunu öğrenebiliriz. has bir yere yazılacaksa, kodda güncel kalmanın en olası olduğu yerdir (etrafında yüzen bazı Word belgelerinden daha olasıdır).