स्व-दस्तावेज कोड क्या है और क्या यह अच्छी तरह से प्रलेखित कोड को बदल सकता है? [बन्द है]

Question

मेरे पास एक सहकर्मी है जो जोर देकर कहता है कि उसके कोड को टिप्पणियों की आवश्यकता नहीं है, यह "स्व दस्तावेज है।"

मैंने उनके कोड की समीक्षा की है, और जबकि यह कोड से अधिक स्पष्ट है जो मैंने दूसरों को देखा है, मैं अभी भी असहमत हूं कि स्व-दस्तावेजीकरण कोड पूर्ण और उपयोगी होने के साथ-साथ टिप्पणी और दस्तावेज कोड भी है।

मुझे उसकी बात समझने में मदद करें ।

• स्व दस्तावेज कोड क्या है
• क्या यह वास्तव में अच्छी तरह से टिप्पणी और दस्तावेज कोड को बदल सकता है
• क्या ऐसी परिस्थितियां हैं जहां यह अच्छी तरह से प्रलेखित और टिप्पणी कोड से बेहतर है
• क्या ऐसे उदाहरण हैं जहां कोड संभवतः टिप्पणियों के बिना स्व-दस्तावेजीकरण नहीं कर सकते हैं

शायद यह सिर्फ मेरी अपनी सीमाएँ हैं, लेकिन मैं यह नहीं देखता कि यह एक अच्छा अभ्यास कैसे हो सकता है।

इसका मतलब तर्क नहीं है - कृपया उन कारणों को सामने न लाएं जिनकी वजह से अच्छी टिप्पणी और दस्तावेज कोड उच्च प्राथमिकता है - ऐसे कई संसाधन हैं जो यह दिखा रहे हैं, लेकिन वे मेरे सहकर्मी के प्रति आश्वस्त नहीं हैं। मेरा मानना ​​है कि मुझे उसे समझाने के लिए उसके दृष्टिकोण को और अधिक पूरी तरह से समझने की आवश्यकता है। एक नया प्रश्न शुरू करें यदि आप अवश्य करें, लेकिन यहाँ बहस न करें।

वाह, त्वरित प्रतिक्रिया! कृपया सभी मौजूदा उत्तरों को पढ़ें और नए उत्तरों को जोड़ने के बजाय उत्तरों को टिप्पणियां प्रदान करें, जब तक कि आपका उत्तर वास्तव में यहां के हर दूसरे उत्तर से काफी अलग हो।

इसके अलावा, आप में से जो स्व-दस्तावेजीकरण कोड के खिलाफ बहस कर रहे हैं, वह मुख्य रूप से स्व-दस्तावेजी कोड इंजीलवादियों के परिप्रेक्ष्य (यानी, सकारात्मक पहलुओं) को समझने में मेरी मदद करना है। यदि आप विषय पर नहीं रहते हैं तो मुझे उम्मीद है कि अन्य लोग आपको नीचा दिखाएंगे।

Comments

तुम्हें पता है कि वास्तव में मुझे क्या प्रभावित करता है? आप उस आदमी से असहमत हैं, लेकिन आप <i> उसे </ i> समझने के लिए कह रहे हैं, उसके खिलाफ अधिक गोला-बारूद के लिए नहीं।

— काजाको

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

— stinky472

संबंधित: thedailywtf.com/Articles/…

— Calmarius

संक्षेप में, कोई भी अधिकांश टिप्पणियों से बच सकता है जो समझाता है कि कोड कैसे काम करता है और उस संबंध में कोड को स्व-दस्तावेजीकरण करता है। लेकिन यह भी अक्सर यह समझाने की आवश्यकता होती है कि कोड उस तरह से क्यों काम करता है, जैसे कि जब आप किसी लाइब्रेरी में एक सीमा के आसपास काम करते हैं। आपको आमतौर पर क्यों की व्याख्या करने के लिए टिप्पणियों की आवश्यकता है।

— लूत्ज प्रीचेल

मैं किसी ऐसे व्यक्ति के साथ काम करता था जो हर चीज पर टिप्पणी करता था, लेकिन आम तौर पर बेकार टिप्पणियों के साथ, जैसे i++; // increment i- लेकिन फ़ंक्शन में उस बिंदु पर वेतन वृद्धि क्यों i होनी चाहिए, इसके बारे में कोई स्पष्टीकरण नहीं है ।

— nnnnnn

Answer 1

मेरी राय में, किसी भी कोड को स्व-दस्तावेजीकरण होना चाहिए। अच्छे, स्व-प्रलेखित कोड में, आपको हर एक पंक्ति की व्याख्या करने की आवश्यकता नहीं है क्योंकि प्रत्येक पहचानकर्ता (चर, विधि, वर्ग) का एक स्पष्ट अर्थ नाम है। आवश्यकता से अधिक टिप्पणियों का होना वास्तव में कोड को पढ़ने के लिए कठिन (!) बनाता है, इसलिए यदि आपका सहकर्मी

• हर वर्ग, सदस्य, प्रकार और विधि के लिए प्रलेखन टिप्पणियाँ (Doxygen, JavaDoc, XML टिप्पणियाँ आदि) लिखते हैं और
• स्पष्ट रूप से कोड के किसी भी हिस्से टिप्पणी है कि कर रहे हैं नहीं आत्म दस्तावेजीकरण और
• कोड के प्रत्येक ब्लॉक के लिए एक टिप्पणी लिखता है जो इरादे की व्याख्या करता है, या कोड एक उच्च अमूर्त स्तर पर क्या करता है (यानी एक निर्देशिका में सभी फ़ाइलों के माध्यम से लूप के बजाय 10 एमबी से बड़ी सभी फ़ाइलों को ढूंढें , यदि फ़ाइल का आकार 10 से बड़ा है तो परीक्षण करें एमबी, अगर रिटर्न सही है तो )

मेरी राय में उसका कोड और प्रलेखन ठीक है। ध्यान दें कि स्व-दस्तावेज कोड का मतलब यह नहीं है कि कोई टिप्पणी नहीं होनी चाहिए, लेकिन केवल यह कि कोई अनावश्यक टिप्पणी नहीं होनी चाहिए। हालाँकि, यह है कि कोड (टिप्पणियों और प्रलेखन टिप्पणियों सहित) को पढ़ने से कोड क्या करता है और क्यों करता है की तत्काल समझ पैदा करनी चाहिए। यदि "स्व-दस्तावेजीकरण" कोड टिप्पणी किए गए कोड की तुलना में समझने में अधिक समय लेता है, तो यह वास्तव में स्व-दस्तावेजीकरण नहीं है।

Comments

इस उत्तर के अनुरूप, मुझे लगता है: memeagora.blogspot.com/2008/11/comments-code-smell.html

— मास्लो

बिंदु एन.आर. 3 बिंदु एनआर का हिस्सा होना चाहिए। 1 IMHO, यदि कोई विधि इतनी जटिल है कि उसे कोड के कई ब्लॉकों के लिए उच्च अमूर्त टिप्पणियों की आवश्यकता होती है, तो कोड के प्रत्येक ऐसे ब्लॉक को एक नया तरीका होना चाहिए।

— बज्रक फ्रंड-हैन्सन

+1 के लिए "इसका मतलब यह नहीं है कि कोई टिप्पणी नहीं होनी चाहिए", जो कुछ लोगों की राय है।

— Skurmedel

अभी भी टिप्पणी करने की आवश्यकता नहीं है कि: सार्वजनिक स्थैतिक संग्रह <फ़ाइल> filesGTTThan (फ़ाइल पथ, int sizeInBytes);

— ट्रायल्क्स

मेरे लिए अंगूठे का एक अच्छा नियम यह है कि टिप्पणियों को कभी भी यह स्पष्ट नहीं करना चाहिए कि WHAT कोड क्या कर रहा है, लेकिन इसका उपयोग यह समझाने के लिए किया जा सकता है कि यह क्यों कर रहा है। दूसरे शब्दों में, यह समझने के लिए कि यह कैसे काम करता है, यह बताने के लिए एक कोड ब्लॉक टिप्पणी करें। यदि आप ब्लॉक को स्पष्ट रूप से नामित विधि में बता सकते हैं, तो यह और भी बेहतर है। यह स्व-दस्तावेजीकरण कोड क्या है।

— मेल

Answer 2

खैर, चूंकि यह टिप्पणियों और कोड के बारे में है, तो आइए कुछ वास्तविक कोड देखें। इस विशिष्ट कोड की तुलना करें:

float a, b, c; a=9.81; b=5; c= .5*a*(b^2);

इस स्व-दस्तावेज कोड के लिए, जो दिखाता है कि क्या किया जा रहा है:

const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

और फिर इस प्रलेखित कोड को, जो बेहतर बताता है कि ऐसा क्यों किया जा रहा है:

/* compute displacement with Newton's equation x = vₒt + ½at² */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

और शून्य टिप्पणियों वाले दस्तावेज के रूप में कोड का अंतिम संस्करण आवश्यक है:

float computeDisplacement(float timeInSeconds) {
    const float gravitationalForce = 9.81;
    float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);
    return displacement;
}

यहाँ एक गरीब टिप्पणी शैली का एक उदाहरण है:

const float a = 9.81; //gravitational force
float b = 5; //time in seconds
float c = (1/2)*a*(b^2) //multiply the time and gravity together to get displacement.

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

मैं कहूंगा कि यह इस बात पर निर्भर करता है कि आप क्या कर रहे हैं। मेरे लिए, स्व-प्रलेखित कोड शायद इस मामले में पर्याप्त है, लेकिन जो कुछ किया गया है उसके पीछे की कार्यप्रणाली का विस्तार से एक टिप्पणी (इस उदाहरण में, समीकरण) भी उपयोगी है।

Comments

वह पूरा हिस्सा वास्तव में एक वर्णनात्मक नाम के साथ एक समारोह में होना चाहिए;)

— वर्कमैड 3

हाँ, कार्य विस्थापनDueToGravity (int timeInSeconds, float gravitationalAcceleration = 9.81) मेरे लिए पढ़ना आसान होगा।

— क्रिश्चियन रोमियो

एक टिप्पणी मुझे यहाँ याद आती है: 5 सेकंड क्यों?

— जॉन निल्सन

वर्णनात्मक फ़ंक्शन नाम के लिए एक और वोट। यह समीकरण खुद नहीं देता है लेकिन मुझे नहीं लगता कि इसकी आवश्यकता है।

— लोरेन Pechtel

गुरुत्वाकर्षण बल की इकाइयाँ क्या हैं? एक चर नाम में आप कितना जोड़ सकते हैं, इसकी सीमाएँ हैं। कुछ बिंदु पर आपको यह समझाना होगा कि आप क्या करने की कोशिश कर रहे हैं । अक्सर यह स्पष्ट नहीं होता है , यही कारण है कि आपको कोड टिप्पणी करने की आवश्यकता है। यह कहने के लिए पूर्ण बकवास है कि कोड स्व-दस्तावेजीकरण है, यह केवल आत्म- वर्णनात्मक है ।

— निक

Answer 3

कोड हमेशा अपने कोड क्या करता है की सबसे अप-टू-डेट स्पष्टीकरण होने जा रहा है, लेकिन मेरी राय में यह आशय की व्याख्या करने के लिए बहुत कठिन है , जो टिप्पणियों का सबसे महत्वपूर्ण पहलू है। यदि यह ठीक से लिखा गया है, तो हम पहले से ही जानते हैं कि कोड क्या करता है, हमें बस यह जानना होगा कि पृथ्वी पर ऐसा क्यों होता है!

Comments

माना। यद्यपि कभी-कभी यहां तक ​​कि सबसे अच्छा कोड भी छिपा सकता है कि इसका अंतिम प्रभाव क्या है, यह टिप्पणियों में क्यों का उत्तर देकर नियंत्रित किया जाता है। जैसा कि, "आपने उन 5 चर को इस तरह से क्यों बदला?"

— सैम एरविन

मेरा 2 सेंचुरी: [यूनिट, स्पेक, बिहेवियर]] मामला कुछ हद तक "पृथ्वी पर क्यों" का जवाब है? फिर आप परीक्षण के मामले को पढ़ सकते हैं और इसे क्यों दिया जाना चाहिए।

— जोन्के

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

— tsellon

और इस प्रकार आपको यह टिप्पणी करनी चाहिए कि जहां अभिप्राय असंदिग्ध नहीं है उसे कोड दिया गया है।

— डेमॉन

@tsellon, आपका स्वचालित युक्ति आपको बता सकता है कि, और अच्छी बात यह कोड है जो कार्यान्वयन कोड की जांच करता है। इसलिए यदि कार्यान्वयन किसी तरह बदलता है, तो कल्पना टूट जाती है। कितना अच्छा है? टिप्पणियां जो आपको कार्यान्वित करती हैं, जब लागू करने वाला कोड वह नहीं करता है जो टिप्पणी अब निर्दिष्ट करती है?

— व्यावहारिक एगिलिस्ट

Answer 4

किसी ने एक बार कहा था

1) कोड के लिए केवल टिप्पणी लिखें जिसे समझना मुश्किल है।
2) ऐसा कोड न लिखने की कोशिश करें जिसे समझना मुश्किल हो।

Comments

कोड लिखने के समय आपको समझना कितना तुच्छ लगता है, वास्तव में किसी और के लिए बाद में समझना बहुत कठिन हो सकता है, भले ही वह कोई और हो या कुछ महीनों / वर्षों में।

— एंडर्स सैंडविग

मुझे अक्सर ऐसी चीजें मिलती हैं जो मैंने शुक्रवार को लिखीं, सोमवार सुबह बहुत मुश्किल से :) :)

— लूफर

जो हमें "टिप्पणियों को न लिखने का प्रयास करने" की ओर ले जाता है

— मुस्तफ़बर

Answer 5

"सेल्फ-डॉक्यूमेंटिंग" कोड के पीछे का विचार यह है कि कोड में वास्तविक प्रोग्राम लॉजिक बहुत स्पष्ट रूप से स्पष्ट है कि कोड पढ़ने वाले किसी को भी यह समझाने के लिए कि कोड क्या कर रहा है, लेकिन यह क्यों कर रहा है।

मेरी राय में, सच स्व-दस्तावेजीकरण कोड का विचार एक मिथक है। कोड आपको बता रहा है कि क्या हो रहा है, इसके पीछे तर्क है, लेकिन यह नहीं समझा सकता है कि यह एक निश्चित तरीके से क्यों किया जा रहा है, खासकर अगर किसी समस्या को हल करने के लिए एक से अधिक तरीके हैं। अकेले उस कारण से यह कभी भी अच्छी टिप्पणी कोड की जगह नहीं ले सकता ।

Comments

IMHO ब्लॉक आपको बताता है कि कैसे , फ़ंक्शन नाम आपको यह बताना चाहिए कि क्यों । जब तक आप दोनों एक साथ उपयोग, आप दोनों के इरादे और कार्यान्वयन .... व्यक्त के रूप में int GetBoundingBox() {return CalcContentDimensions() + this.padding + this.margin;}...

— बेसिक

Answer 6

मुझे लगता है कि यह सवाल करना प्रासंगिक है कि क्या कोड की एक विशेष पंक्ति स्व-दस्तावेजीकरण है, लेकिन अंत में यदि आप कोड के एक स्लाइस की संरचना और कार्य को नहीं समझते हैं, तो अधिकांश समय टिप्पणी मदद करने वाली नहीं है। उदाहरण के लिए, "सही ढंग से टिप्पणी की गई" कोड के amdfan के स्लाइस:

/* compute displacement with Newton's equation x = v0t + ½at^2 */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

यह कोड ठीक है, लेकिन निम्नलिखित अधिकांश आधुनिक सॉफ्टवेयर सिस्टम में समान रूप से जानकारीपूर्ण है, और स्पष्ट रूप से पहचानता है कि न्यूटनियन गणना का उपयोग करना एक विकल्प है जिसे बदल दिया जा सकता है कुछ अन्य शारीरिक प्रतिमान अधिक उपयुक्त होना चाहिए:

const float accelerationDueToGravity = 9.81;
float timeInSeconds = 5;
float displacement = NewtonianPhysics.CalculateDisplacement(accelerationDueToGravity, timeInSeconds);

मेरे अपने व्यक्तिगत अनुभव में, बहुत कम "सामान्य" कोडिंग स्थितियां हैं जहां आपको बिल्कुल टिप्पणियों की आवश्यकता है। उदाहरण के लिए, आप कितनी बार अपने खुद के एल्गोरिथ्म को समाप्त करते हैं? मूल रूप से बाकी सब कुछ आपके सिस्टम को संरचित करने का मामला है ताकि एक कोडर उपयोग में संरचनाओं और उन विकल्पों को समझ सके जो उन विशेष संरचनाओं का उपयोग करने के लिए सिस्टम को निकालते हैं।

Comments

आपको अधिक upvotes की आवश्यकता है, आपका उदाहरण बताता है कि क्यों हम दस्तावेज़ के इरादे के लिए फ़ंक्शन नाम का उपयोग करना चाहिए।

— एप-इनोगो

Answer 7

मैं भूल गया कि मुझे यह कहाँ से मिला, लेकिन:

एक कार्यक्रम में प्रत्येक टिप्पणी पाठक के लिए एक माफी की तरह है। "मुझे खेद है कि मेरा कोड इतना अपारदर्शी है कि आप इसे देखकर इसे समझ नहीं सकते"। हमें सिर्फ यह स्वीकार करना है कि हम पूर्ण नहीं हैं, लेकिन पूर्ण होने का प्रयास करते हैं और जब हमें आवश्यकता होती है तब माफी मांगते हुए सही होते हैं।

Comments

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

— स्कॉट डोरमैन

अगर दो पूरी तरह से सही तरीके हैं, तो इससे कोई फर्क नहीं पड़ता कि आपने एक को दूसरे पर क्यों चुना?

— ईबीग्रीन

हाँ, समान रूप से सही का मतलब सटीक नहीं है। एक विधि दूसरे की तुलना में कुछ स्थितियों में तेज हो सकती है।

— इक्के

यदि आपके निर्णय मानदंड में गति है, तो वे एकांत सुधार नहीं हैं। मैं यह नहीं कह रहा हूं कि टिप्पणियां खराब हैं। बस इसके लिए उनकी आवश्यकता होती है क्योंकि वर्तमान में कोई प्रोग्रामिंग भाषा नहीं है जो इतनी स्पष्ट है कि कोई भी स्पष्ट रूप से कोड को देख सकता है और कोड के इरादे को तुरंत जान सकता है।

— ईबीग्रीन

मुझे नहीं लगता कि लोग uderstand है कि उसी तरह से बोली कि मैं क्या करता हूं। मेरा यह मतलब है कि आपको हमेशा ऐसा कोड लिखने का प्रयास करना चाहिए जो इतना स्पष्ट हो कि उसे टिप्पणी करने की आवश्यकता न हो, लेकिन आपको यह स्वीकार करना होगा कि यह एक ऐसा आदर्श है जो कभी वास्तविकता में काम नहीं करता है।

— ईबीग्रीन

Answer 8

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

सेल्फ-डॉक्यूमेंटिंग कोड वह कोड होता है जिसमें किसी जानकार पाठक को यह समझने के लिए कि उसे क्या करना है, फ्री-टेक्स्ट टिप्पणियों की आवश्यकता नहीं है। उदाहरण के लिए, कोड का यह टुकड़ा स्व-दस्तावेजीकरण है:

print "Hello, World!"

और ऐसा है:

factorial n = product [1..n]

और ऐसा है:

from BeautifulSoup import BeautifulSoup, Tag

def replace_a_href_with_span(soup):
    links = soup.findAll("a")
    for link in links:
        tag = Tag(soup, "span", [("class", "looksLikeLink")])
        tag.contents = link.contents
        link.replaceWith(tag)

अब, "सूचित पाठक" का यह विचार बहुत व्यक्तिपरक और स्थितिजन्य है। यदि आपको या किसी और को आपके सहकर्मी के कोड का पालन करने में परेशानी हो रही है, तो वह एक सूचित पाठक के अपने विचार का फिर से मूल्यांकन करने के लिए अच्छा करेगा। कोड सेल्फ-डॉक्यूमेंटिंग कॉल करने के लिए भाषा और पुस्तकालयों के साथ परिचित स्तर का उपयोग किया जाना चाहिए।

"सेल्फ-डॉक्यूमेंटिंग कोड" लिखने के लिए मैंने जो सबसे अच्छा तर्क देखा है, वह यह है कि यह फ्री-टेक्स्ट कमेंटरी की समस्या से बचता है क्योंकि यह कोड के साथ सहमत नहीं है जैसा कि लिखा गया है। सबसे अच्छी आलोचना यह है कि जब कोड यह वर्णन कर सकता है कि यह क्या और कैसे कर रहा है, तो यह नहीं समझा सकता है कि कुछ को एक निश्चित तरीके से क्यों किया जा रहा है।

Answer 9

स्व-दस्तावेजीकरण कोड "DRY" (खुद को दोहराएं नहीं) का एक अच्छा उदाहरण है। टिप्पणियों की जानकारी डुप्लिकेट न करें, जो कोड में ही है, या हो सकती है।

यह समझने के बजाय कि एक चर का उपयोग किस लिए किया जाता है, चर का नाम बदलें।

कोड का एक छोटा स्निपेट क्या करता है, यह समझाने के बजाय, इसे एक विधि में निकालें और इसे एक वर्णनात्मक नाम दें (शायद आपके टिप्पणी पाठ का छोटा संस्करण)।

यह समझने के बजाय कि एक जटिल परीक्षण क्या करता है, इसे एक विधि में भी निकालें और इसे एक अच्छा नाम दें।

आदि।

इसके बाद आप उस कोड के साथ समाप्त हो जाते हैं जिसमें अधिक स्पष्टीकरण की आवश्यकता नहीं होती है, यह खुद को समझाता है, इसलिए आपको उन टिप्पणियों को हटाना चाहिए जो कोड में केवल जानकारी दोहराते हैं।

इसका मतलब यह नहीं है कि आपके पास कोई टिप्पणी नहीं है, कुछ जानकारी है जिसे आप कोड में नहीं डाल सकते हैं जैसे कि इरादे के बारे में जानकारी ("क्यों")। आदर्श मामले में कोड और टिप्पणियां एक दूसरे के पूरक हैं, प्रत्येक दूसरे में जानकारी की नकल किए बिना अद्वितीय व्याख्यात्मक मूल्य जोड़ते हैं।

Comments

एक अपवाद: खराब प्रोग्रामर। मैंने टिप्पणी देखी है कि कोड कुछ ऐसा कर रहा है जो ऐसा नहीं है। फिर मैं खुद से पूछता हूं: क्या मुझे कोड या टिप्पणी ठीक करनी चाहिए?

— गाइड

आप उद्देश्य-सी में विधि के नाम को हरा नहीं सकते। :)

Answer 10

सेल्फ-डॉक्यूमेंटिंग कोड एक अच्छा अभ्यास है और अगर ठीक से किया जाए तो बहुत अधिक टिप्पणियों को पढ़े बिना आसानी से कोड का अर्थ बता सकते हैं। विशेष रूप से उन परिस्थितियों में जहां टीम में सभी को अच्छी तरह से समझा जाता है।

यह कहने के बाद कि, टिप्पणियां नए कामर्स के लिए या परीक्षकों के लिए या प्रलेखन / सहायता फ़ाइलों को उत्पन्न करने के लिए बहुत सहायक हो सकती हैं।

स्व-दस्तावेजीकरण कोड + आवश्यक टिप्पणियां टीमों में लोगों की मदद करने की दिशा में एक लंबा रास्ता तय करेगी।

Answer 11

क्रम में:

• सेल्फ-डॉक्यूमेंटिंग कोड वह कोड है जो स्पष्ट रूप से पाठक को अपना इरादा व्यक्त करता है।
• पूरी तरह से नहीं। टिप्पणियां हमेशा टिप्पणी के लिए सहायक होती हैं कि किसी विशेष रणनीति को क्यों चुना गया। हालांकि, टिप्पणियाँ जो बताती हैं कि कोड का एक भाग क्या कर रहा है, कोड के संकेत हैं जो अपर्याप्त रूप से स्व-दस्तावेजीकरण है और कुछ रिफैक्टिंग का उपयोग कर सकता है।
• टिप्पणियाँ झूठ और तारीख से बाहर हो जाती हैं। कोड हमेशा बताता है कि सच बताने की अधिक संभावना है।
• मैं एक मामले में जहां कभी नहीं देखा है क्या कोड की टिप्पणियों के बिना पर्याप्त रूप से स्पष्ट नहीं किया जा सकता है; हालांकि, जैसे कि मैंने पहले कहा, यह कभी कभी आवश्यक / उपयोगी पर टिप्पणी शामिल करने के लिए है क्यों ।

हालांकि, यह नोट करना महत्वपूर्ण है कि वास्तव में स्व-दस्तावेजीकरण कोड बहुत सारे स्व-और टीम-अनुशासन लेता है। आपको अधिक घोषित रूप से प्रोग्राम करना सीखना होगा, और आपको बहुत विनम्र होना होगा और कोड के पक्ष में "चतुर" कोड से बचना होगा जो इतना स्पष्ट है कि ऐसा लगता है कि किसी ने भी इसे लिखा हो सकता है।

Comments

मैं यहाँ एक नाइट पिक डालूँगा। कोड हमेशा "सच बताओ" नहीं है। कोड भ्रामक हो सकता है और इसके इरादों को बहुत आसानी से बाधित कर सकता है। उदाहरण के लिए, एक गलत वैरिएबल या विधि केवल आउट ऑफ डेट टिप्पणी के रूप में झूठ बोल सकती है।

— वेज

विधि के नाम झूठ बोल सकते हैं और पुरानी भी हो सकती हैं।

— कैलमेरियस

Answer 12

जब आप "सेल्फ-डॉक्यूमेंटिंग कोड" पढ़ते हैं, तो आप देखते हैं कि यह क्या कर रहा है, लेकिन आप हमेशा अनुमान नहीं लगा सकते कि यह उस विशेष तरीके से क्यों कर रहा है।

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

जब आप रखरखाव करते हैं, तो उन बैकग्राउंड जानकारी बहुत महत्वपूर्ण हो जाती है।

बस मेरी चुटकी भर नमक…

Answer 13

एक के लिए, निम्नलिखित स्निपेट पर विचार करें:

/**
 * Sets the value of foobar.
 *
 * @foobar is the new vaue of foobar.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

इस उदाहरण में आपके पास कोड की प्रति 3 पंक्तियों में 5 पंक्तियाँ हैं। इससे भी बदतर - टिप्पणियों में कुछ भी नहीं जोड़ा जाता है जिसे आप कोड पढ़कर नहीं देख सकते हैं। यदि आपके पास इस तरह के 10 तरीके हैं, तो आप 'टिप्पणी अंधापन' प्राप्त कर सकते हैं और पैटर्न से भटकने वाली एक विधि पर ध्यान नहीं दे सकते।

यदि निश्चित रूप से, एक बेहतर संस्करण होता:

/**
 * The serialization of the foobar object is used to synchronize the qux task.
 * The default value is unique instance, override if needed.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

फिर भी, तुच्छ कोड के लिए मुझे टिप्पणी नहीं करना पसंद है। आशय और समग्र संगठन को कोड के बाहर एक अलग दस्तावेज़ में बेहतर तरीके से समझाया गया है।

Comments

यह दस्तावेज़ पाने वालों और बसने वालों को तुच्छ लग सकता है, लेकिन मुझे लगता है कि बेकार टिप्पणी करने और कोई टिप्पणी नहीं करने के बीच एक खुशहाल माध्यम है। Javadoc टिप्पणियों का एक बहुत बिंदु किसी को सूचित करना है जो विधि में कोड को देखने या न करने के लिए झुकाव नहीं कर सकता है।

— जेम्स मैकमोहन

Answer 14

अंतर "क्या" और "कैसे" के बीच है।

• आपको "क्या" एक नियमित दस्तावेज़ करना चाहिए।
• आपको "कैसे" यह दस्तावेज़ नहीं करना चाहिए, जब तक कि विशेष मामले (उदाहरण के लिए एक विशिष्ट एल्गोरिथ्म पेपर का उल्लेख न करें)। यह स्व-दस्तावेज होना चाहिए।

Comments

दृढ़तापूर्वक असहमत। नाम से एक दिनचर्या क्या स्पष्ट होनी चाहिए। यह कैसे करता है यह कार्यान्वयन कोड से स्पष्ट होना चाहिए। कार्यान्वयन को क्यों लिखा गया क्योंकि इसे दस्तावेज होना चाहिए ।

— एंथनी मैनिंग-फ्रैंकलिन

Answer 15

एक बात जो आप अपने सहकर्मी को इंगित करना चाह सकते हैं, वह यह है कि कोई फर्क नहीं पड़ता कि उसका कोड कितना स्व-दस्तावेजी है, यदि अन्य वैकल्पिक दृष्टिकोणों पर विचार किया गया और त्याग दिया गया कि जानकारी खो जाएगी जब तक कि वह उस जानकारी के साथ कोड टिप्पणी नहीं करता। कभी-कभी यह जानना उतना ही महत्वपूर्ण होता है कि एक विकल्प पर विचार किया गया था और यह क्यों तय किया गया था और कोड टिप्पणियों के समय के साथ जीवित रहने की सबसे अधिक संभावना है।

Comments

आप इसे एक नियम के रूप में लेते हैं और आप अपने कोडबेस में पाठ्यपुस्तक लिखना समाप्त कर देंगे ;-) मैं हालांकि गैर-स्पष्ट निर्णयों के लिए सहमत हूं।

— ddimitrov

@ddimitrov, यह एक अच्छा अवलोकन है। लेकिन जैसा कि आप गैर-स्पष्ट निर्णयों के लिए कहते हैं (और वे आमतौर पर ऐसे होते हैं जिन्हें वास्तव में वैसे भी प्रलेखन की आवश्यकता होती है) यह एक अच्छा अभ्यास है।

— ओनोरियो कैटेनेशिया

उस कोड का दस्तावेज़ जो लिखा नहीं गया था ! :)

— टोनी

Answer 16

एक कंपनी में जहां मैंने काम किया था, उनमें से एक प्रोग्रामर ने निम्नलिखित को उसकी निगरानी के शीर्ष पर अटका दिया था।

"अपने कोड को उस व्यक्ति की तरह दस्तावेज़ करें जो इसे बनाए रखता है यह एक होमोसेक्सुअल पागल है जो जानता है कि आप कहाँ रहते हैं।"

Answer 17

सेल्फ-डॉक्यूमेंटिंग कोड आम तौर पर वैरिएबल नामों का उपयोग करता है, जो कोड को ठीक से मेल खाते हैं ताकि यह समझना आसान हो जाए कि क्या चल रहा है

हालांकि, इस तरह के "स्व-दस्तावेजीकरण कोड" कभी भी टिप्पणियों की जगह नहीं लेगा। कभी-कभी कोड बहुत जटिल होता है और स्व-दस्तावेजीकरण कोड पर्याप्त नहीं होता है, विशेष रूप से रखरखाव के तरीके में।

मेरे पास एक बार एक प्रोफेसर थे जो इस सिद्धांत में दृढ़ विश्वास रखते थे। वास्तव में सबसे अच्छी बात जो मैंने उन्हें याद करते हुए कही कि "टिप्पणियाँ बहनों के लिए हैं"
यह हम सभी को पहली बार आश्चर्यचकित करता है लेकिन यह समझ में आता है।
हालाँकि, स्थिति यह है कि भले ही आप यह समझने में सक्षम हों कि कोड में क्या चल रहा है, लेकिन कोई ऐसा व्यक्ति जो कम अनुभवी है कि आप अपने पीछे आ सकता है और यह नहीं समझ सकता कि क्या हो रहा है। यह तब है जब टिप्पणियां महत्वपूर्ण हो जाती हैं। मैं कई बार जानता हूं कि हमें विश्वास नहीं है कि वे महत्वपूर्ण हैं लेकिन ऐसे बहुत कम मामले हैं जहां टिप्पणियां अनावश्यक हैं।

Comments

फिर इसे साफ होने तक रिफ्लेक्टर करें। मैं एक दृढ़ विश्वासी हूँ कि कुछ भी ऐसा नहीं है जिसे कोड द्वारा स्पष्ट रूप से नहीं कहा जा सकता है।

— टाइग्रेन

सिवाय इसके कि एक विशिष्ट कार्यान्वयन, एल्गोरिथ्म, या सूत्र को एक समान रूप से सही एक पर चुना गया था। आप कभी यह नहीं बता सकते हैं कि एक विकल्प कोड में क्यों बनाया गया था, केवल वह विकल्प क्या था।

— स्कॉट डोरमैन

@scott: आप दोनों विकल्पों को एक बड़े वर्ग के तहत रख सकते हैं और अन्य को एक टिप्पणी के साथ अनइम्प्लीमेंटेड छोड़ सकते हैं ... ओह प्रतीक्षा करें।

— एपे-इनोगो

Answer 18

मुझे आश्चर्य है कि किसी ने भी " लिटरेट प्रोग्रामिंग " के बारे में नहीं लाया है , 1981 में TeX के डोनाल्ड ई। नूथ और "द आर्ट ऑफ़ कंप्यूटर प्रोग्रामिंग" ख्याति द्वारा विकसित तकनीक।

आधार सरल है: चूंकि कोड को एक मानव द्वारा समझा जाना है और टिप्पणियों को केवल संकलक द्वारा फेंक दिया जाता है, इसलिए हर किसी को उनकी ज़रूरत की चीज़ नहीं दें - कोड के इरादे का एक पूर्ण पाठ विवरण, प्रोग्रामिंग भाषा आवश्यकताओं द्वारा अनफिल्टर्ड संकलक के लिए मानव पाठक और शुद्ध कोड के लिए।

साक्षर प्रोग्रामिंग उपकरण आपको एक दस्तावेज के लिए विशेष मार्कअप देकर ऐसा करते हैं जो यह बताता है कि उपकरण क्या स्रोत होना चाहिए और पाठ क्या है। कार्यक्रम बाद में दस्तावेज़ से स्रोत कोड भागों को चीरता है और एक कोड फ़ाइल को इकट्ठा करता है।

मुझे इसका वेब पर एक उदाहरण मिला: http://moonflare.com/code/select/select.nw या HTML संस्करण http://moonflare.com/code/select/select.html

यदि आप एक पुस्तकालय (डोनाल्ड ई। नुथ, लिटरेट प्रोग्रामिंग, स्टैनफोर्ड, कैलिफ़ोर्निया: सेंटर फॉर द स्टडी ऑफ़ लैंग्वेज एंड इंफॉर्मेशन, 1992, CSLI लेक्चर नोट्स, संख्या 27।) में इस पर नथ की पुस्तक पा सकते हैं, तो आपको इसे देखना चाहिए।

यह स्व-दस्तावेजीकरण कोड है, जो तर्क और सभी के साथ पूरा होता है। यहां तक ​​कि एक अच्छा दस्तावेज़ बनाता है, बाकी सब कुछ सिर्फ अच्छी तरह से लिखा टिप्पणी है :-)

Comments

यह वास्तव में स्व-दस्तावेज कोड के विपरीत है। मानव के लिए पाठ, मशीन के लिए कोड। और कोड किस भाषा का होना चाहिए? विधानसभा की। मनुष्य को इसे पढ़ने की आवश्यकता नहीं है, है ना? उन्हें केवल इसे लिखने की आवश्यकता है!

— १३:३०

Answer 19

मैं कई मान्य उत्तरों के लिए एक और परिप्रेक्ष्य देना चाहूंगा:

सोर्स कोड क्या है? प्रोग्रामिंग भाषा क्या है?

मशीनों को स्रोत कोड की आवश्यकता नहीं है। वे विधानसभा चलाने में खुश हैं। प्रोग्रामिंग लैंग्वेज हमारे फायदे के लिए हैं। हम विधानसभा नहीं लिखना चाहते हैं। हमें यह समझने की जरूरत है कि हम क्या लिख ​​रहे हैं। प्रोग्रामिंग कोड लिखने के बारे में है।

क्या आप जो लिख रहे हैं उसे पढ़ने में सक्षम होना चाहिए?

स्रोत कोड मानव भाषा में नहीं लिखा गया है। यह (उदाहरण के लिए फोरट्रान) की कोशिश की गई है, लेकिन यह पूरी तरह से सफल नहीं है।

स्रोत कोड में अस्पष्टता नहीं हो सकती है। इसलिए हमें पाठ की तुलना में इसमें अधिक संरचना डालनी होगी। पाठ केवल संदर्भ के साथ काम करता है, जिसे हम पाठ का उपयोग करते समय प्रदान करते हैं। सोर्स कोड में संदर्भ हमेशा एक्सप्लिसिट होता है। सी # में "का उपयोग करें" सोचो।

अधिकांश प्रोग्रामिंग भाषाओं में अतिरेक होता है ताकि संकलक हमें पकड़ सके जब हम सुसंगत नहीं हैं। अन्य भाषाएं अधिक अनुमान का उपयोग करती हैं और उस अतिरेक को खत्म करने का प्रयास करती हैं।

कंप्यूटरों के प्रकार, विधि के नाम और परिवर्तनशील नाम की जरूरत नहीं है। वे हमारे द्वारा संदर्भित करने के लिए उपयोग किए जाते हैं। संकलक शब्दार्थ को नहीं समझता है, यह हमारे लिए उपयोग करने के लिए है।

प्रोग्रामिंग भाषाएं मनुष्य और मशीन के बीच एक भाषाई सेतु हैं। यह हमारे लिए लिखने योग्य है और उनके लिए पठनीय है। माध्यमिक मांगें हैं कि यह हमारे लिए पठनीय होना चाहिए। यदि हम शब्दार्थ में अच्छे हैं जहां अनुमति दी गई है और कोड को संरचित करने में अच्छा है, तो स्रोत कोड को हमारे लिए भी पढ़ना आसान होना चाहिए। सर्वश्रेष्ठ कोड को टिप्पणियों की आवश्यकता नहीं है।

लेकिन जटिलता हर परियोजना में छिप जाती है, आपको हमेशा यह तय करना होगा कि जटिलता कहां रखी जाए और कौन सा ऊंट निगल जाए। टिप्पणियों का उपयोग करने के लिए वे स्थान हैं।

Answer 20

सेल्फ डॉक्यूमेंटिंग कोड समस्या का एक आसान विकल्प है, जो समय कोड, टिप्पणी और प्रलेखन से अलग है। और यह स्पष्ट कोड लिखने के लिए एक अनुशासनात्मक कारक है (यदि आप खुद पर सख्त हैं)।

मेरे लिए, ये नियम हैं जिनका मैं पालन करने की कोशिश करता हूं:

• कोड जितना संभव हो उतना आसान और स्पष्ट होना चाहिए।
• टिप्पणियों को मेरे द्वारा लिए गए डिजाइन निर्णयों के लिए कारण देना चाहिए, जैसे: मैं इस एल्गोरिथ्म का उपयोग क्यों करता हूं, या कोड की सीमाएं होती हैं, जैसे: जब काम नहीं करता है ... (यह कोड में एक अनुबंध / दावे में संभाला जाना चाहिए) (आमतौर पर) फ़ंक्शन / प्रक्रिया के भीतर)।
• दस्तावेज़ीकरण को उपयोग (अभिसरण कॉलिंग), साइड इफेक्ट्स, संभावित रिटर्न मानों को सूचीबद्ध करना चाहिए। इसे jDoc या xmlDoc जैसे टूल का उपयोग करके कोड से निकाला जा सकता है। इसलिए यह आमतौर पर फ़ंक्शन / प्रक्रिया के बाहर होता है, लेकिन कोड के करीब इसका वर्णन करता है।

इसका मतलब यह है कि कोडिंग कोड के सभी तीन साधन एक साथ रहते हैं और इसलिए कोड बदलने पर परिवर्तन होने की अधिक संभावना है, लेकिन वे जो व्यक्त करते हैं उसमें ओवरलैप नहीं होते हैं।

Answer 21

तथाकथित स्व-दस्तावेजीकरण कोड के साथ वास्तविक समस्या यह है कि यह बताती है कि यह वास्तव में क्या करता है। हालांकि कुछ टिप्पणियां किसी को कोड को बेहतर तरीके से समझने में मदद कर सकती हैं (जैसे, एल्गोरिदम के चरण, आदि) यह एक हद तक बेमानी है और मुझे संदेह है कि आप अपने सहकर्मी को मना लेंगे।

हालांकि, प्रलेखन में वास्तव में जो महत्वपूर्ण है वह सामान है जो सीधे कोड से स्पष्ट नहीं है: अंतर्निहित इरादे, मान्यताओं, प्रभाव, सीमाएं आदि।

यह निर्धारित करने में सक्षम होना कि एक कोड एक त्वरित नज़र से एक्स करता है, यह निर्धारित करने में सक्षम होने की तुलना में आसान है कि एक कोड वाई नहीं करता है। उसे वाई दस्तावेज करना है ...

आप उसे एक ऐसे कोड का उदाहरण दिखा सकते हैं जो अच्छी तरह से दिखता है, स्पष्ट है, लेकिन वास्तव में इनपुट के सभी आधारों को कवर नहीं करता है, उदाहरण के लिए, और देखें कि क्या वह पाता है।

Answer 22

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

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

संपादित करें: मुझे (और शायद हर किसी को) शायद यह प्रावधान करना चाहिए कि डिजिटल सिग्नल प्रोसेसिंग (डीएसपी) ऐप पर बहुत अच्छी टिप्पणी की जानी चाहिए। इसका मुख्य कारण यह है कि डीएसपी ऐप्स अनिवार्य रूप से मानों के सरणियों के साथ खिलाए गए छोरों के लिए 2 हैं और जोड़ता / गुणा / आदि ने कहा मूल्यों ... प्रोग्राम को बदलने के लिए आप किसी एक सरणियों में मूल्यों को बदलते हैं ... क्या कहने के लिए टिप्पणियों की एक जोड़ी की आवश्यकता है आप उस मामले में कर रहे हैं;)

Comments

तो एक फ़ंक्शन या वेरिएबल नाम यह बताने के लिए पर्याप्त तुच्छ स्पष्ट संदर्भ प्रदान करेगा कि किसी समस्या को हल करने के लिए दो या अधिक समान रूप से सही तरीके से एक कार्यान्वयन को क्यों चुना गया?

— स्कॉट डोरमैन

Answer 23

गणितीय कोड लिखते समय, मैंने कभी-कभी लंबी, निबंध जैसी टिप्पणियों को लिखने के लिए उपयोगी पाया है, गणित की व्याख्या करते हुए, कोड का उपयोग करने वाले कुख्यात सम्मेलनों, और यह सब एक साथ कैसे फिट बैठता है। हम यहाँ दस्तावेज़ों की सैकड़ों पंक्तियों की बात कर रहे हैं।

मैं अपने कोड को संभव के रूप में स्व-दस्तावेज़ीकरण बनाने की कोशिश करता हूं, लेकिन जब मैं कुछ महीनों के बाद इस पर काम करने के लिए वापस आता हूं, तो मुझे वास्तव में इसके बाहर हैश बनाने से रखने के लिए स्पष्टीकरण को पढ़ने की आवश्यकता है।

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

लेकिन बहुत सारे कोड को समझ बनाने के लिए टिप्पणियों की आवश्यकता होती है, इसलिए इसे जितना संभव हो सके स्पष्ट रूप से लिखें और फिर जितनी आवश्यकता हो उतने टिप्पणियों का उपयोग करें ...

Answer 24

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

अच्छा डोमेन मॉडलिंग 
+ अच्छे नाम (संस्करण, विधियाँ, कक्षाएं) 
+ कोड उदाहरण (उपयोग मामलों से इकाई परीक्षण) 
= स्व दस्तावेज सॉफ्टवेयर 

Answer 25

कोड के अतिरिक्त अतिरिक्त टिप्पणियों के कारणों की एक जोड़ी स्पष्ट हो सकती है:

• जिस कोड को आप देख रहे हैं वह स्वचालित रूप से जेनरेट किया गया था, और इसलिए कोड को संपादित करने के बाद अगली बार परियोजना के संकलित होने की संभावना हो सकती है
• प्रदर्शन लाभ के लिए एक कम-से-सीधा कार्यान्वयन को बंद कर दिया गया था (एक लूप को अनियंत्रित करना, एक महंगी गणना के लिए एक लुकअप तालिका बनाना, आदि)

Answer 26

यह सब होने जा रहा है कि टीम अपने प्रलेखन में क्या महत्व रखती है। मैं सुझाव दूंगा कि डॉक्यूमेंटिंग क्यों / इरादे के बजाय कि कैसे महत्वपूर्ण है और यह हमेशा सेल्फ डॉक्यूमेंटिंग कोड में कैद नहीं होता है। get / set नहीं ये स्पष्ट हैं - लेकिन गणना, पुनर्प्राप्ति आदि क्यों व्यक्त की जानी चाहिए।

यदि आप विभिन्न राष्ट्रीयताओं से आ रहे हैं, तो अपनी टीम में अंतर के बारे में भी जानकारी रखें। डिक्शन में अंतर तरीकों के नामकरण में कमी कर सकते हैं:

BisectionSearch

द्विआधारी खोज

BinaryChop

3 अलग-अलग महाद्वीपों पर प्रशिक्षित डेवलपर्स के इन तीन तरीकों ने एक ही काम किया। एल्गोरिदम का वर्णन करने वाली टिप्पणियों को पढ़कर ही हम अपने पुस्तकालय में दोहराव की पहचान करने में सक्षम थे।

Answer 27

मेरे लिए रीडिंग कोड जिसे टिप्पणियों की आवश्यकता है, वह उस भाषा में पाठ पढ़ने जैसा है जिसे मैं नहीं जानता। मैं बयान देखता हूं और मुझे समझ में नहीं आता है कि यह क्या करता है या क्यों - और मुझे टिप्पणियों को देखना है। मैंने एक वाक्यांश पढ़ा और मुझे समझने के लिए शब्दकोश में देखने की जरूरत है कि इसका क्या मतलब है।

आमतौर पर कोड को लिखना आसान होता है कि स्व-दस्तावेज यह क्या करता है। आपको यह बताने के लिए कि यह ऐसा क्यों करता है टिप्पणियाँ अधिक उपयुक्त हैं, लेकिन यहां तक ​​कि कोड भी बेहतर हो सकता है। यदि आप अमूर्त के हर स्तर पर अपने सिस्टम को समझते हैं, तो आपको अपने कोड को व्यवस्थित करने का प्रयास करना चाहिए

public Result whatYouWantToDo(){
  howYouDoItStep1();
  howYouDoItStep2();
  return resultOfWhatYouHavDone;
}

जहां विधि नाम आपके इरादे को दर्शाता है और विधि निकाय बताता है कि आप अपने लक्ष्य को कैसे प्राप्त करते हैं। आप वैसे भी पूरी पुस्तक को इसके शीर्षक में नहीं बता सकते हैं, इसलिए आपके सिस्टम के मुख्य सार को अभी भी प्रलेखित किया जाना है, साथ ही साथ जटिल एल्गोरिदम, गैर-तुच्छ विधि अनुबंध और कलाकृतियों को भी।

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

Answer 28

अधिकांश दस्तावेज़ीकरण / टिप्पणियां भविष्य के कोड एन्हांसर्स / डेवलपर्स की सहायता के लिए काम करते हैं, इसलिए कोड को बनाए रखने योग्य बनाते हैं। अधिक बार हम नई सुविधाओं को जोड़ने या अनुकूलन करने के लिए बाद में अपने मॉड्यूल पर वापस आने का प्रयास नहीं करेंगे। उस समय कई ब्रेकप्वाइंट के माध्यम से कदम की तुलना में टिप्पणियों को पढ़ने के द्वारा कोड को समझना आसान होगा। इसके अलावा मैं मौजूदा तर्क को समझने के बजाय नए तर्क के लिए सोचने में समय बिताऊंगा।

Answer 29

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

इसका मतलब यह नहीं है कि कोड पर टिप्पणी नहीं की जानी चाहिए। इसका मतलब है कि टिप्पणियों को एक कारण प्रदान करना चाहिए कि कोड को जिस तरह से लिखा गया है।

Answer 30

मेरा मानना ​​है कि आपको हमेशा स्व-दस्तावेजीकरण कोड प्राप्त करने का प्रयास करना चाहिए क्योंकि इससे कोड को पढ़ना आसान हो जाता है। हालाँकि, आपको चीजों के बारे में व्यावहारिक होना भी चाहिए।

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

यह सिर्फ मेरी राय है। मैं ऐसे बहुत सारे लोगों के बारे में जानता हूं जो बिना किसी टिप्पणी के काम करते हैं और कहते हैं कि उन्हें लगता है कि यह कोई समस्या नहीं है। हालाँकि, मैंने किसी से छह महीने पहले लिखी गई विधि के बारे में पूछा था और मुझे यह बताने के लिए कुछ मिनटों के लिए सोचना पड़ा कि यह क्या किया है। यह एक समस्या नहीं है अगर विधि टिप्पणी की है।

अंत में, आपको यह याद रखना होगा कि टिप्पणियाँ कोड के समान सिस्टम का हिस्सा हैं। जैसा कि आप रिफ्लेक्टर करते हैं और कार्यक्षमता बदलते हैं, आपको अपनी टिप्पणियों को भी अपडेट करना होगा। यह उन टिप्पणियों का उपयोग करने के खिलाफ एक तर्क है क्योंकि वे गलत होने पर बेकार से बदतर हैं।