फ़ील्ड में एक प्रलेखन शीर्षलेख होना चाहिए - स्टाइल कॉप - कोड गंध?

Question

मैं बस अपना कोड के कुछ के खिलाफ शैली पुलिस चल रहा था और मिला कुछ:

SA1600: The field must have a documentation header. 

अब नहीं मिलता मुझे गलत मैं शैली पुलिस, यह बहुत अच्छा है जब आप एक से अधिक व्यक्ति के साथ एक परियोजना पर काम की तरह लेकिन यह नियम मेरे लिए थोड़ा अधिक लगता है। आप जोड़ने के लिए क्यों चाहिए:

/// <summary> 
    /// blah blah blah 
    /// </summary> 

हर चर के शीर्ष करने के

। मुझे पूरा यकीन है कि मुझे किसी को यह कहते हुए याद है (मार्टिन फाउलर, केंट बेक ... वास्तव में एटीएम को याद नहीं कर सकता) कि टिप्पणी कहनी चाहिए "क्यों" नहीं "क्या" और मैं वास्तव में नहीं देख सकता कि आप कैसे समझा सकते हैं चर।

मुझे कोड भी मिलता है जिसमें हर चरणीय हार्डर पर पढ़ने के लिए टिप्पणियां होती हैं क्योंकि आप जो भी देखते हैं वह फ्लफ है।

मेरे विचार हैं अगर आपको यह समझाना है कि प्रत्येक चर क्या है तो आप वास्तव में नामकरण के मामले में असफल हो रहे हैं।

क्या कोई और टिप्पणी कोड को थोड़ा गंध कोड ढूंढता है या यह सिर्फ मुझे है।

Answer 1

मैं यह नहीं कहूंगा कि एक चर पर टिप्पणी करना हमेशा एक कोड गंध होता है (और यह वही नहीं लगता है जो आप कह रहे हैं)। मैं सहमत हूं कि प्रत्येक एकल चर पर टिप्पणी करते हुए, हर बार कम से कम अत्यधिक, और संभावित रूप से खराब नामकरण का संकेत मिलता है। वास्तव में, कुछ तर्क देंगे कि कोई भी टिप्पणी एक कोड गंध है, और वर्णनात्मक नाम और लघु दिनचर्या अधिक पठनीय हैं और स्थिति को रोकते हैं जहां कोड बदल दिया गया है, लेकिन टिप्पणियां अपडेट नहीं की गई हैं (जिसने मुझे निश्चित रूप से काट दिया है कुछ विरासत कोड अड्डों में)। मुझे नहीं लगता कि मैं इसे काफी दूर ले जाऊंगा, लेकिन यदि आप कोड लिख सकते हैं जो अतिरिक्त स्पष्टीकरण के बिना स्वयं व्याख्यात्मक है, तो यह बेहतर लगता है।

तो हाँ, मूल रूप से आपने जो कहा था।

Answer 2

मुझे लगता है कि यहां सही जवाब "यह निर्भर करता है।" आप निश्चित रूप से वैरिएबल की सामग्री पर स्थिर/कॉन्स, या व्यावसायिक तर्क/प्रतिबंधों को चिह्नित करने वाले चर के "क्यों" को समझा सकते हैं। ऐसा कहकर, मैं मानता हूं कि प्रत्येक परिवर्तनीय टिप्पणी को पढ़ने योग्यता में बाधा डालती है और मानक या अनुचित नामकरण के बाद अंधेरे से संकेत दे सकती है।

Answer 3

एक्सएमएल टिप्पणियां अन्य टिप्पणियों की तुलना में थोड़ा अलग हैं।

यदि आप चीजों को सही तरीके से सेट करते हैं, तो आप उन्हें विजुअल स्टूडियो में टूल टिप्स में प्रकट कर सकते हैं और रेत कैसल के साथ एमएसडीएन स्टाइल दस्तावेज़ बनाने के लिए उनका उपयोग कर सकते हैं। मुझे लगता है कि उन्हें आपको बताना चाहिए कि जब आप स्रोत कोड तक पहुंच नहीं पाते हैं तो क्या काम कर रहा है।

बिंदु यह है कि ये टिप्पणियां उन स्रोत कोड के बिना दिखाई दे सकती हैं, जिन पर वे टिप्पणी कर रहे हैं। उन्हें एक अन्य devloper के लिए सहायक होना चाहिए जो आपका कोड नहीं देख सकता है और आप कम काम कर रहे हैं कि आप कैसे काम कर रहे हैं।

मुझे आपके द्वारा उपयोग किए जा रहे "कॉप" टूल के बारे में पता नहीं है, लेकिन यह अच्छा होगा कि उपकरण को सिग्नल करने का एक तरीका है जो एक परम खाली छोड़ने का इरादा रखता है। तो:

/// <param name="fubar"></param> // Haven't gotten around to it 
    /// <param name="portNumber" /> // I intend this parameter to have no help 

मैं परियोजनाओं जहाँ हम में सब कुछ को भरने के लिए है पर काम किया है और हम तरह बातें मिलती है:

/// <param name="portNumber">The Port Number</param> // What else could it be? 

आप ऊपर सुविधाओं का उपयोग, जाना आगे बंद करने के लिए नहीं करना चाहते हैं स्टाइल पुलिस नियम।

Answer 4

पूरी तरह से सहमत हैं और स्टाइलकॉप में पहली चीज़ जो मैंने बंद कर दी है। यदि आपको इसे समझाने की आवश्यकता है, तो आपने इसे एक ऐसे फैशन में नामित किया है जिसके लिए स्पष्टीकरण की आवश्यकता है और self documenting कोड बनाने में विफल रहा है।

Answer 5

आपको GhosDoc को अपने आवेदन पर प्रत्येक कोड सदस्य के लिए स्वचालित रूप से प्रलेखन करने का एक आसान तरीका है। बस इसे स्थापित करें, सदस्य पर राइट क्लिक करें और इसे दस्तावेज़ का चयन करें!

Answer 6

यह काफी पुरानी पोस्ट है लेकिन इस मुद्दे के समाधान के लिए खोज करते समय इसे पार किया, हालांकि मैं समाधान प्रदान करता हूं।

आप नियमों संपादक में अपने Settings.StyleCop फ़ाइल खोलते हैं, तो प्रलेखन नियम नोड का चयन करें, तो विस्तृत सेटिंग में सही पर अनुभाग का चयन रद्द क्षेत्रों को शामिल करें विकल्प। अब आपको फ़ील्ड दस्तावेज करने की आवश्यकता नहीं होगी।

Answer 7

उन लोगों के लिए जो अभी भी इस मुद्दे पर आते हैं, इस पोस्ट how-to-change-a-stylecop-rule वास्तव में सही उत्तर है।