टिप्पणी-आउट कोड मूल्यवान प्रलेखन हो सकता है?


83

मैंने निम्नलिखित कोड लिखा है:

if (boutique == null) {
    boutique = new Boutique();

    boutique.setSite(site);
    boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
    boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
    boutique.setNom(fluxBoutique.getNom());
    boutique.setSelected(false);
    boutique.setIdWebSC(fluxBoutique.getId());
    boutique.setDateModification(new Date());

    boutiqueDao.persist(boutique);
} else {
    boutique.setSite(site);
    boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
    boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
    boutique.setNom(fluxBoutique.getNom());
    //boutique.setSelected(false);
    boutique.setIdWebSC(fluxBoutique.getId());
    boutique.setDateModification(new Date());

    boutiqueDao.merge(boutique);
}

यहाँ एक टिप्पणी-बाहर लाइन है। लेकिन मैं इसे कोड साफ बनाता है, स्पष्ट कर रही है क्या अंतर के बीच है से लगता है ifऔर else। रंग हाइलाइटिंग के साथ अंतर और भी अधिक ध्यान देने योग्य है।

क्या इस तरह से टिप्पणी करना एक अच्छा विचार हो सकता है?

जवाबों:


109

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

पहले, बाहर टिप्पणी कोड संकलित नहीं है। यह स्पष्ट है, लेकिन इसका मतलब है कि:

  1. कोड भी काम नहीं कर सकता है।

  2. जब टिप्पणी की निर्भरता बदल जाती है तो यह स्पष्ट रूप से नहीं टूटेगा।

टिप्पणी कोड बहुत "मृत कोड" है। यह जितना लंबा बैठता है, उतना ही यह घूमता है और अगले डेवलपर को कम और कम मूल्य प्रदान करता है।

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

विकल्पों पर विचार करें:

  • यदि फ़ंक्शन एक फ़ंक्शन / एपीआई का उपयोग करने के उदाहरण प्रदान करता है, तो एक इकाई परीक्षण प्रदान करें। इकाई परीक्षण वास्तविक कोड हैं, और तब टूटेंगे जब वे अब सही नहीं होंगे।
  • यदि उद्देश्य कोड के पिछले संस्करण को संरक्षित करना है, तो स्रोत नियंत्रण का उपयोग करें। मैं बहुत बार पिछले संस्करण की जांच करूंगा और फिर एक बदलाव को "वापस" करने के लिए कोडबेस में टिप्पणियों को टॉगल करूंगा।
  • यदि उद्देश्य समान कोड के वैकल्पिक संस्करण को बनाए रखना है , तो स्रोत नियंत्रण (फिर से) का उपयोग करें। यही कारण है कि शाखाओं के लिए, सब के बाद कर रहे हैं।
  • यदि उद्देश्य संरचना को स्पष्ट करना है, तो विचार करें कि आप इसे और अधिक स्पष्ट करने के लिए कोड का पुनर्गठन कैसे कर सकते हैं। अधिकांश अन्य उत्तर इस बात के अच्छे उदाहरण हैं कि आप ऐसा कैसे कर सकते हैं।

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

14
प्रोग्रामिंग भाषा की तुलना में मानव भाषा में डिज़ाइन विकल्पों को बेहतर तरीके से समझाया गया है।
मार्क ई। हासे

3
बाद के डेवलपर्स के लिए यह कैसे संभव होगा कि मेरी परियोजना को ले जाए, यह पता चले कि स्रोत नियंत्रण में एक वैकल्पिक / पिछला / विफल कार्यान्वयन मौजूद है? क्या नए डेवलपर्स को सभी संस्करण इतिहासों से गुजरने और लॉग बदलने की उम्मीद है? या हर उपयोगी वैकल्पिक कार्यान्वयन के लिए पिछले कमिट के हैश से लिंक करने के लिए टिप्पणी का उपयोग करना एक आम बात है? यदि हां, तो मैंने कभी गौर नहीं किया।
Moobie

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

263

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

यदि आप एक boutiqueDao.mergeOrPersistविधि बनाते हैं तो आप इसे फिर से लिख सकते हैं:

if (boutique == null) {
    boutique = new Boutique();
    boutique.setSelected(false);
}

boutique.setSite(site);
boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
boutique.setNom(fluxBoutique.getNom());
boutique.setIdWebSC(fluxBoutique.getId());
boutique.setDateModification(new Date());

boutiqueDao.mergeOrPersist(boutique);

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

कई ओआरएम ने किसी तरह से इसके समर्थन में निर्माण किया है। उदाहरण के लिए, यदि वे idशून्य हैं, तो वे एक नई पंक्ति बना सकते हैं और idशून्य न होने पर किसी मौजूदा पंक्ति को अपडेट कर सकते हैं। सटीक रूप ORM पर निर्भर करता है, और जब से मैं आपके द्वारा उपयोग की जा रही तकनीक से परिचित नहीं हूं, मैं आपकी मदद नहीं कर सकता।


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

bool isNewBoutique = boutique == null;
if (isNewBoutique) {
    boutique = new Boutique();
    boutique.setSelected(false);
}

boutique.setSite(site);
boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE + fluxBoutique.getLogo());
boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE + fluxBoutique.getUrl());
boutique.setNom(fluxBoutique.getNom());
boutique.setIdWebSC(fluxBoutique.getId());
boutique.setDateModification(new Date());

if (isNewBoutique)
    boutiqueDao.persist(boutique);
else
    boutiqueDao.merge(boutique);

166

यह बिल्कुल भयावह विचार है। यह स्पष्ट नहीं करता है कि इरादा क्या है। क्या डेवलपर ने गलती से रेखा पर टिप्पणी की थी? कुछ परीक्षण करने के लिए? क्या चल रहा है?!

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


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

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

इस पोस्ट में इसी तरह का दृष्टिकोण: कोड आउट के साथ कोडबेस को प्रदूषित न करें
निक एलेक्सीव

120

नहीं, यह एक भयानक विचार है। कोड के उस टुकड़े के आधार पर निम्नलिखित विचार मेरे दिमाग में आते हैं:

  • इस लाइन पर टिप्पणी की गई क्योंकि डेवलपर इसे डिबग कर रहा था और अपने पूर्व राज्य में लाइन को बहाल करना भूल गया था
  • इस लाइन पर टिप्पणी की गई है क्योंकि यह एक बार व्यापार तर्क का हिस्सा था, लेकिन अब ऐसा नहीं है
  • इस लाइन पर टिप्पणी की गई क्योंकि इससे उत्पादन पर प्रदर्शन की समस्या पैदा हो गई और डेवलपर यह देखना चाहता था कि उत्पादन प्रणाली पर क्या प्रभाव पड़ा है

कोड की टिप्पणी की हजारों पंक्तियों को देखने के बाद, मैं अब एकमात्र समझदार काम कर रहा हूं जब मैं इसे देखता हूं: मैं इसे तुरंत हटा देता हूं।

कोड में एक रिपॉजिटरी में टिप्पणी करने के लिए कोई समझदार कारण नहीं है।

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


1
हालाँकि मुझे डुप्लिकेट कोड से छुटकारा मिल गया है, यह शायद ही एक अनुकूलन के रूप में देखा जा सकता है, मुझे लगता है।
एलेक्सिस डुफ्रेनॉय

23
यह मानव पठनीयता के लिए एक अनुकूलन है
jk।

11
@ यदि आप गति, मेमोरी उपयोग, बिजली की खपत या किसी अन्य मीट्रिक के लिए अनुकूलन कर सकते हैं तो मुझे नहीं लगता कि आप पठनीयता के लिए अनुकूलन नहीं कर सकते हैं (हालांकि मीट्रिक के रूप में यह थोड़ा वूलेयर है)
jk।

3
वास्तव में, मेरा मतलब मानवीय पठनीयता से था। यहां छोटा संकेत: प्रोग्रामिंग में आपका सबसे महत्वपूर्ण दायित्व आपका कोड है। तो, कम वास्तव में यहाँ अधिक है।
डिब्बेके

4
एक देयता के रूप में सॉफ़्टवेयर का इलाज c2.com/cgi/wiki?SoftwareAsLiable पर भी किया जाता है : "अधिक कोड का उत्पादन करना हमेशा एक लाभ नहीं होता है। कोड परीक्षण करना और बनाए रखना महंगा होता है, इसलिए यदि समान कोड कम कोड के साथ किया जा सकता है।" एक प्लस है। डेड कोड को कमेंट न करें, बस इसे डिलीट कर दें। कमेंट किया गया कोड बासी और बेकार हो जाता है, इसलिए आप अव्यवस्था को कम करने के लिए इसे जल्द से जल्द डिलीट कर सकते हैं, इसे आसान बनाने के लिए अच्छे बैकअप रखें। । "
नवजाल

51

मैं कोड्स इनचैचोस के उत्तर में जोड़ना चाहूंगा, यह इंगित करके कि आप इसे छोटे तरीकों में और सुधार कर सकते हैं । रचना द्वारा सामान्य कार्यक्षमता साझा करना सशर्त से बचा जाता है:

function fill(boutique) {    
  boutique.setSite(site);
  boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
  boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
  boutique.setNom(fluxBoutique.getNom());
  boutique.setIdWebSC(fluxBoutique.getId());
  boutique.setDateModification(new Date());
}    

function create() {
  boutique = new Boutique();      
  fill(boutique);
  boutique.setSelected(false);
  return boutiqueDao.persist(boutique);
}

function update(boutique) {
  fill(boutiquie);
  return boutiquieDao.merge(boutique); 
}

function createOrUpdate(boutique) {
  if (boutique == null) {
    return create();
  }
  return update(boutique);  
}

6
मुझे लगता है कि यहां सबसे साफ सुझाव है।
एलेक्सिस डफ्रेनॉय 15

+1, और मैं यह भी जोड़ूंगा कि जितना अधिक आप nullवस्तुओं के आसपास से गुजरने से बचते हैं, उतना बेहतर (मुझे लगता है कि यह समाधान एक अच्छा उदाहरण है)।
नादिर संपोली

मैं boutiqueDaoइनपुट के रूप में पास करूँगा createऔर update
हैप्पी ग्रीन किड नेप्स

यह कैसे काम कर सकता है? आप कैसे जान सकते हैं कि कब कॉल करें और कब कॉल अपडेट करें? मूल कोड बुटीक को देखता है और जानता है कि उसे अपडेट करने या बनाने की आवश्यकता है या नहीं। यह सिर्फ तब तक कुछ नहीं करता जब तक आप कॉल या अपडेट नहीं करते ...
Lyrion

Lyrion: तुच्छ, मैं स्पष्टता के लिए उस कोड को जोड़ दूँगा।
अलेक्जेंडर टॉर्लिंग

27

हालांकि यह स्पष्ट रूप से टिप्पणी के लिए एक अच्छा मामला नहीं है कोड के बारे में एक स्थिति है कि मुझे लगता है कि यह वारंट है:

// The following code is obvious but does not work because of <x>
// <offending code>
<uglier answer that actually does work>

यह एक चेतावनी है जो कोई भी इसे बाद में देखता है कि स्पष्ट सुधार नहीं है।

संपादित करें: मैं कुछ छोटे के बारे में बात कर रहा हूं। अगर यह बड़ा है तो आप इसके बजाय समझाएं।


5
इसमें गलत क्या है // the following part done like it is because of X? समझाएं कि आपने कुछ ऐसा क्यों किया जो आपने किया था, न कि आपने इसे किसी विशेष तरीके से क्यों नहीं किया । आपके विशेष उदाहरण में, यह पूरी तरह से कमेंट-आउट कोड के एक बड़े ब्लॉक की आवश्यकता को पूरी तरह से समाप्त कर देता है। (मैं नीचे नहीं था, लेकिन निश्चित रूप से देख सकता हूं कि यह क्यों
खराब

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

1
@GarrettAlbright: धन्यवाद, मुझे खुशी है कि किसी को यह देखकर खुशी हुई।
लोरेन Pechtel

3
@ लोरेनपेकटेल: केवल इतना ही नहीं, मैं कमोबेश उसी के बारे में लिख रहा था। ऐसी परिस्थितियां हैं जहां यह बहुत ही उपयोगी है, जल्दी से यह जानने के लिए कि "स्पष्ट" समाधान पहले से ही सफलता के बिना करने की कोशिश की गई है और वे काम क्यों नहीं करते हैं।
जेएनएसजी

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

14

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

// इस बुटीक को अचयनित करने की आवश्यकता नहीं है, क्योंकि [WHATEVER]

हालाँकि, मुझे लगता है कि कुछ परिस्थितियाँ ऐसी हैं जहाँ छोड़ना (या टिप्पणी को जोड़ना भी) कोड निंदनीय नहीं है। MATLAB या NumPY जैसी किसी चीज़ का उपयोग करते समय, अक्सर एक समान कोड लिख सकते हैं जो या तो 1) एक सरणी पर पुनरावृत्त करता है, एक समय में एक तत्व को संसाधित करता है या 2) एक बार में पूरे सरणी को संचालित करता है। कुछ मामलों में, उत्तरार्द्ध बहुत तेज़ है, लेकिन पढ़ने के लिए भी बहुत कठिन है। यदि मैं कुछ कोड को उसके सदिश समतुल्य के साथ प्रतिस्थापित करता हूं, तो मैं मूल कोड को पास की टिप्पणी में एम्बेड करता हूं, जैसे:

%% नीचे दिया गया वेक्टर कोड ऐसा करता है:

% for ii in 1:N
%    for jj in 1:N
%      etc.

% लेकिन मैट्रिक्स संस्करण चलाता है ~ 15x तेजी से विशिष्ट इनपुट पर (एमके, 03/10/2013)

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


"जाहिर है, किसी को यह ध्यान रखने की ज़रूरत है कि दो संस्करण वास्तव में एक ही काम करते हैं और टिप्पणी या तो साथ रहती है ..." - वहीं आपने समझाया कि यह एक अच्छा विचार क्यों नहीं है।
14:27 बजे स्लेस्के

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

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

1
आपके अंतिम मामले में मैं दोनों कोड वेरिएंट को कंपाइलेबल कोड के रूप में रखूंगा।
कोडइन्चोएज

12

एकमात्र बार जब मैंने टिप्पणी-आउट कोड देखा, जो उपयोगी था, कॉन्फिग फाइलों में था, जहां हर विकल्प के लिए कोड प्रदान किया गया था, लेकिन टिप्पणी की गई, जिससे टिप्पणी मार्करों को हटाकर सेटिंग्स को सक्षम करना आसान हो गया:

## Enable support for mouse input:
# enable_mouse = true

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


7

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

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


2
यह बात काफी हद तक सच है। बहुत सारे लोग (स्वयं शामिल) सोचते हैं कि उनका कोड इतना भयानक है कि उसे प्रलेखन की आवश्यकता नहीं है। हालांकि, दुनिया में हर कोई इसे अच्छी तरह से दस्तावेज और टिप्पणी नहीं करता है, जब तक कि यह gobbledygook पाता है।
रयान अमोस

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

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

4

नहीं, टिप्पणी की गई कोड बासी हो जाती है, और जल्द ही बेकार से भी बदतर होती है, यह अक्सर हानिकारक होती है, क्योंकि यह कार्यान्वयन के कुछ पहलू के साथ-साथ सभी मौजूदा मान्यताओं को भी मजबूत करती है।

टिप्पणियों में इंटरफ़ेस विवरण और इच्छित फ़ंक्शन शामिल होना चाहिए; "इच्छित कार्य": शामिल कर सकते हैं, पहले हम यह कोशिश करते हैं, फिर हम कोशिश करते हैं, फिर हम इस तरह से विफल हो जाते हैं।

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


2

यह बहुत ही दुर्लभ मामलों में हो सकता है, लेकिन जैसा आपने किया है वैसा नहीं है। अन्य जवाब बहुत अच्छी तरह से उस के कारणों से बाहर निकाल दिया है।

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

Name:           foomatic
Version:        3.14
 ...
Source0:        %{name}-%{version}.tar.gz

बिना स्रोतों के पैकेज के लिए, हम टैग को टिप्पणी करते हैं और मानक प्रारूप को बनाए रखने के लिए इसके ऊपर एक और टिप्पणी करते हैं और संकेत करते हैं कि किसी ने विकास प्रक्रिया के भाग के रूप में समस्या के बारे में रोका और सोचा है:

Name:           barmatic
Version:        2.71
 ...
# This package has no sources.
# Source0:        %{name}-%{version}.tar.gz

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

if ( condition ) {
  foo();
  // Under most other circumstances, we would do a bar() here, but
  // we can't because the quux isn't activated yet.  We might call
  // bletch() later to rectify the situation.
  baz();
}

5
यकीनन वह टिप्पणी कोड से टिप्पणी नहीं की गई है।
जे.के.

1
@ जक: आप यकीनन सही हैं।
’११ में ब्लरफ्ल

1

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

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

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


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

1
कृपया "प्रयुक्त" को परिभाषित करें।
जेएनएसजी

मुझे लगता है कि उनका मतलब "निष्पादित" था
एलेक्सिस डुफ्रेनॉय

-2

यह अच्छा दोस्त नहीं दिखता है।

टिप्पणी कोड है ... कोड नहीं। कोड तर्क के कार्यान्वयन के लिए है। अपने आप में एक कोड को अधिक पठनीय बनाना एक कला है। जैसा कि @CodesInChaos ने पहले ही सुझाव दिया है कि कोड की दोहरावदार लाइनें तर्क का बहुत अच्छा कार्यान्वयन नहीं हैं

क्या आप वास्तव में सोचते हैं कि एक सच्चा प्रोग्रामर तार्किक कार्यान्वयन पर पठनीयता को प्राथमिकता देगा। (जिस तरह से हमारे पास टिप्पणियाँ और 'बस्तियाँ' हैं जो हमारे तार्किक प्रतिनिधित्व में हैं)।

जहां तक ​​मेरा सवाल है कि कंपाइलर के लिए एक कोड लिखना चाहिए और यह अच्छा है - अगर 'यह' उस कोड को समझता है। मानव पठनीयता के लिए टिप्पणियाँ अच्छी हैं, डेवलपर्स के लिए (लंबे समय में), उस कोड का पुन: उपयोग करने वाले लोगों के लिए (जैसे परीक्षक)।

अन्यथा आप यहां कुछ और अधिक लचीली कोशिश कर सकते हैं, कुछ ऐसा

bique.setSite (साइट) के साथ प्रतिस्थापित किया जा सकता है

setsiteof.boutique (साइट)। OOP के विभिन्न पहलू और परिप्रेक्ष्य हैं जिनके माध्यम से आप पठनीयता बढ़ा सकते हैं।

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


15
"जहां तक ​​मेरा सवाल है, कंपाइलर के लिए एक कोड लिखना चाहिए" ओह प्लीज, नहीं। इस तरह से आप राक्षसी के साथ अंत करते हैं जो यह देखते हैं कि उन्हें सीधे सी प्रतियोगिता और पसंद से लिया जा सकता है। कंप्यूटर द्विआधारी हैं, जबकि मनुष्य फजी लॉजिक का उपयोग करते हैं (यह पालतू मालिकों के लिए दोगुना हो जाता है, वैसे)। कंप्यूटर का समय आज मुफ्त में है (मूल रूप से सिर्फ बिजली के उपयोग के लिए) जबकि प्रोग्रामर का समय तुलनात्मक रूप से बहुत महंगा है। मनुष्यों के लिए कोड लिखें, और संकलक इसे समझेंगे। संकलक के लिए मनुष्यों की परवाह किए बिना कोड लिखें, और आप टीम में कई दोस्त नहीं बनाएंगे।
बजे एक CVn

3
" एक संकलक के लिए कोड लिखें " - वास्तव में आप नहीं। आपको जिस व्यक्ति को ध्यान में रखना चाहिए वह वही है जिसने आपके कोड को बनाए रखने के लिए कार्य सौंपा है।
जेएनएसजी
हमारी साइट का प्रयोग करके, आप स्वीकार करते हैं कि आपने हमारी Cookie Policy और निजता नीति को पढ़ और समझा लिया है।
Licensed under cc by-sa 3.0 with attribution required.