स्पष्टता के लिए कोडिंग मानक: कोड की प्रत्येक पंक्ति पर टिप्पणी करें?


142

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

मैंने छात्र कोड को भी वर्गीकृत किया है जिसमें कोई टिप्पणी नहीं थी और यह देखा कि उन्हें उपेक्षित करने के लिए उन्हें चिह्नित क्यों किया जाना चाहिए।

मैं समझता हूं कि अच्छे नामों का उपयोग करना, संरचनाओं को सरल रखना, कार्यों को छोटा और मॉड्यूल को ध्यान में रखते हुए कोड को पर्याप्त रूप से समझ में रखेगा कि टिप्पणियों को कम से कम किया जा सकता है।

मैं यह भी समझता हूं कि टिप्पणियों को यह बताना चाहिए कि कोड क्या करता है, कैसे नहीं।

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

चेकलिस्ट में एक पंक्ति के रूप में व्यवहार किए जाने पर इस तरह के कोड का एक उदाहरण की आवश्यकता हो सकती है:

/* Display an error message */
function display_error_message( $error_message )
{
    /* Display the error message */
    echo $error_message;

    /* Exit the application */
    exit();
}

/* -------------------------------------------------------------------- */

/* Check if the configuration file does not exist, then display an error */
/* message */
if ( !file_exists( 'C:/xampp/htdocs/essentials/configuration.ini' ) ) {
    /* Display an error message */
    display_error_message( 'Error: Configuration file not found. Application has stopped');
}

यदि यह एक मानक दस्तावेज़ में इसे ठीक से व्यक्त करना संभव है, और यह बस नहीं हो सकता है, तो मैं इन पंक्तियों के साथ एक विचार पर कब्जा करना चाहता हूं:

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


21
टिप्पणियाँ विस्तारित चर्चा के लिए नहीं हैं; इस वार्तालाप को बातचीत में स्थानांतरित कर दिया गया है ।
मेपल_शाफ्ट

32
"टिप्पणियाँ विस्तारित चर्चा के लिए नहीं हैं" यहां तक ​​कि कोड टिप्पणियों के लिए भी। :) वे /* Display an error message */टिप्पणियाँ भयानक हैं और वास्तव में पठनीयता को प्रभावित करती हैं।
एंड्रिया लेज़रोज़ेटो

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

1
@ डौग.मार्कफ़्लन मुझे लगा कि विम के लिए मौजूद होना चाहिए। बेशक यह फ़ाइल और ब्लॉक दोनों स्तरों पर करता है - rtfm-sarl.ch/articles/hide-comments.html !
माइकल डुरंट

1
इसके अलावा टॉगल करें - stackoverflow.com/a/11842371/631619
माइकल ड्यूरेंट

जवाबों:


171

माइकल डुरंट का जवाब IMHO बुरा नहीं है, लेकिन यह वस्तुतः सवाल का जवाब नहीं दे रहा है (जैसा कि उसने खुद स्वीकार किया है), इसलिए मैं एक उत्तर देने की कोशिश करूंगा जो करता है:

मैं यह भी समझता हूं कि टिप्पणियों को यह बताना चाहिए कि कोड क्या करता है, कैसे नहीं।

यह सब देखते हुए क्या यह अच्छा कोडिंग मानकों को लिखना संभव है जो इस विचार को पकड़ते हैं?

जाहिर है आप अपने कोड समीक्षाओं के लिए एक चेकलिस्ट लिख सकते हैं , जैसे प्रश्न

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

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

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


45
किसने इसे नकारा? यह महत्वपूर्ण सॉफ्टवेयर विकास का उत्तर है। यह एक अलग दुनिया है जहाँ अधिकांश प्रोग्रामर काम करते हैं। इन दुनियाओं में, एक कोडिंग मानक जो अपनी टिप्पणी के लिए कोड की हर एक पंक्ति को कॉल करता है, वह सही उत्तर नहीं है। न ही टिप्पणियों के लिए जा रहा है। OTOH, कोड समीक्षा के अधीन टिप्पणी करना महत्वपूर्ण सॉफ्टवेयर के लिए बिल्कुल सही तरह का मानक है। यह अधिक समीक्षा योग्य और बनाए रखने योग्य कोड के लिए बनाता है, लेकिन यह एक लागत पर आता है। यह लागत मल्टी-मिलियन डॉलर के मुकदमों की तुलना में कम है, जो खराब लिखे गए सॉफ़्टवेयर के परिणामस्वरूप हैं।
डेविड हैमेन

4
बुद्धिमान उत्तर। यदि हम कोडिंग के लिए वास्तविक नियम खोज सकते हैं, तो हमें प्रोग्रामर की आवश्यकता नहीं होगी। हम बस मशीनों कोड हो सकता है। यह हो सकता है! :(

4
@David Hammen: आपकी टिप्पणी के लिए धन्यवाद। वास्तव में, मुझे लगता है कि यह केवल "महत्वपूर्ण सॉफ़्टवेयर विकास" पर लागू नहीं होता है। प्रत्येक टुकड़ा सॉफ्टवेयर, जो वर्षों से बनाए रखा और विकसित किया गया है, अक्सर विभिन्न लोगों द्वारा, अगले रखरखाव प्रोग्रामर के लिए समझने योग्य मधुमक्खी से लाभ होगा।
डॉक्टर ब्राउन

5
यह किसी भी कोडिंग के लिए अच्छी सलाह है , न कि विभिन्न लोगों द्वारा बनाए गए कोड के लिए। यहां तक ​​कि अगर आप एक स्क्रिप्ट / प्रोग्राम का उपयोग करने वाले केवल एक हैं, तो भविष्य में आपको एक वर्ष में कोड को संशोधित करना होगा, स्पष्टता की सराहना करेगा (और अपारदर्शी कोड को डिक्रिप्ट नहीं करने से बचाया गया समय)।
एंथोनी जोगेगन

5
क्या आप किसी और उद्देश्य के लिए "वर्तमान में सबसे अधिक उत्तर दिया गया उत्तर" संपादित कर सकते हैं? हर पाठक इन उत्तरों के वोट इतिहास को जानने वाला नहीं है।
कैंडिड_ऑरेंज

151

कम स्पष्टता के साथ खराब गुणवत्ता कोड के लिए प्रमुख विरोधी पैटर्न

btw पाठकों, शीर्षक मूल रूप से था "कोड की हर पंक्ति टिप्पणी?" और आप हम में से कई लोगों की सहज प्रतिक्रिया की कल्पना कर सकते हैं। मैं बाद में अधिक सटीक शीर्षक से पीछे हट गया।

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

डेवलपर बदतर कोड लिखना चाहेंगे। वे अधिक गूढ़ नामों और संरचनाओं का उपयोग करेंगे क्योंकि 'इसकी टिप्पणी में समझाया गया है - देखें!'।

विचार करें:

living_room_set = tables + chairs.

अब विचार करें:

set = tbls+chrs # Make the set equal to the table plus the chairs

आपके पास न केवल अधिक गूढ़ नाम और पढ़ने के लिए दोनों हैं, आपको आगे-पीछे भी देखना होगा, कोड को देखना होगा, एक सेट क्या है? कोड पर बाएं देखें, टिप्पणियों पर दाएं देखें, tbls क्या हैं, कोड पर बाएं देखें, टिप्पणियों पर दाएं देखें, chrs क्या हैं, टिप्पणी पर दाईं ओर देखें। Yuch!

सारांश

यदि आप एक डेवलपर के रूप में अपनी वर्तमान स्थिति में मजबूर हैं, तो एक टिप्पणी मानक को विकसित या बढ़ाएं (जैसा कि एक पूर्व COBOL प्रोग्रामिंग मैंने बड़े लोगों को देखा है!) लेकिन अपने समय, ऊर्जा और जुनून के रूप में ज्यादा खर्च किया। तर्कों का उपयोग करते हुए पैटर्न:

  • कोड और टिप्पणियाँ एक दूसरे के साथ सिंक से बाहर निकलते हैं जब केवल एक ही बदल जाता है

  • टिप्पणियाँ वर्णन कर सकती हैं कि एक व्यक्ति क्या सोचता है लेकिन गलत हो सकता है और इस प्रकार बग को कवर कर सकता है

  • कोड को पढ़ना मुश्किल हो जाता है

  • अच्छा कोड लिखने के लिए कठिन हो जाता है

  • अधिक गूढ़ नामों का उपयोग करने की प्रवृत्ति

  • कोड और टिप्पणियों में पढ़ने के लिए अत्यधिक वर्ण

  • विभिन्न संपादक विभिन्न शैलियों का उपयोग करते हैं

  • केवल कोडिंग की तुलना में उच्च अंग्रेजी भाषा दक्षता की आवश्यकता है

  • समय और संसाधन लेता है और दीर्घकालिक मूल्य से घटाता है *

प्लस इस तरह की टिप्पणियों के बिना बेहतर कोड के लिए तर्क देता है , - वास्तव में एक मानक (!) है - सभी चर नाम full_english_words होना चाहिए - एक है! इसलिए अच्छी तरह से लिखित कोड और परीक्षणों के मानकों के प्रति उस 'मानकों' ऊर्जा का उपयोग करें।

दो कठिन समस्याओं में से एक चीजों का नामकरण है - टिप्पणियों के साथ समस्या को न छोड़ें।

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

* कल कोड


8
मुझे विश्वास नहीं होता कि आपने प्रश्न का उत्तर दिया। सवाल हर लाइन पर टिप्पणी करने का नहीं है। यह पूछ रहा है कि डेवलपर्स को हर पंक्ति में टिप्पणी करने के लिए बिना कोड बताने के लिए कैसे कहा जाए।
22

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

1
दूसरी कठिन समस्या क्या है?
डेविड ग्रिनबर्ग


1
टिप्पणियों से बचने के लिए आपके प्रत्येक कारण को काउंटर किया जा सकता है, लेकिन StackExchange मेरे लिए लंबे समय तक पर्याप्त टिप्पणियां (हेह) की अनुमति नहीं देता है जो मुझे यहां संबोधित करता है। बस: ओवरकॉम्बिंग मतदाता धोखाधड़ी की तरह है: ऐसा होता है, लेकिन बहुत कम ही; आखिरी बार आपने वास्तव में कब ऐसा होते देखा था? अच्छी टिप्पणियाँ लिखना केवल एक सोच के बाद नहीं होना चाहिए; यदि सही ढंग से किया जाता है, तो यह विकास प्रक्रिया में मदद करता है। हाँ, यह संसाधन लेता है, लेकिन भुगतान बेहतर कोड है। आप एक बेहतर चर नामकरण मानक के लिए टिप्पणियों का बलिदान करके अपने हिरन के लिए एक ही धमाका नहीं कर पाएंगे। हां, हर पंक्ति में टिप्पणी करना पागल है।
kmoser

23

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

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

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


63
इस रैकेट में 40 से अधिक वर्षों के बाद मैंने जो कुछ सीखा है, उनमें से एक यह है कि सामान्य ज्ञान बिल्कुल सामान्य नहीं है।
जॉन आर। स्ट्रॉहम

10
सामान्य ज्ञान जैसी कोई चीज नहीं है।
whatsisname

1
in_programming no .. वास्तविक दुनिया ओह हाँ, लेकिन वास्तविक दुनिया के लिए इसका सिर्फ एक शब्द है अनुभवी ज्ञान
माइकल डुरंट

@ JohnR.Strohm: मेरा अनुभव आपकी तुलना में बहुत अधिक सकारात्मक रहा है, लेकिन मैंने यह भी देखा है कि किस तरह से सामान्य ज्ञान के उपयोग को यांत्रिक रूप से लागू करने वाले नियमों द्वारा सक्रिय रूप से हतोत्साहित किया जा सकता है।
जैक्सबी

मैं इस जवाब के साथ 99.9% समझौते में हूं। कोड रिव्यू में जब कोई डिबेट होती है तो कोडिंग स्टैंडर्ड का मतलब डेवलपर्स से होता है। कोड की समीक्षा उत्पाद को समृद्ध करने के लिए होती है जो युद्धों को शुरू नहीं करती है। इतने सारे युद्धों को मैंने कोड रिव्यू द्वारा किसी भी कोडिंग स्टैंडर्ड के साथ नहीं देखा है। मैं यह कहने की हिम्मत करता हूं कि यदि आप कोडिंग मानक में वस्तुओं की जांच को स्वचालित नहीं कर सकते हैं तो यह वहां होना चाहिए। एक कोड समीक्षा अन्य कम अनुभवी डेवलपर्स को 'सामान्य ज्ञान' प्रदान करने का समय है। यह चर के नामकरण पर लड़ने का समय नहीं है। लिनक्स / कर्नेल / gen_init_cpio.c लाइन 335.
एंड्रयू टी फिनेल

19

यह संभव नहीं है। आप जो अनिवार्य रूप से करने की कोशिश कर रहे हैं वह अच्छे निर्णय को मशीनीकरण करने के लिए है।

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

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


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

1
@Wildcard शायद आप समझा सकते हैं कि एक मानक निर्णय के लिए अनुमति कैसे दे सकता है? उस बिंदु पर एक गाइड नहीं होगा? एक मानक "एक विचार या चीज है जिसका उपयोग तुलनात्मक मूल्यांकन में एक उपाय, आदर्श या मॉडल के रूप में किया जाता है।" कोई व्यक्ति व्यक्तिपरक रूप से किसी वस्तु का उपयोग कैसे कर सकता है, इसलिए यह व्यक्तिपरक है जो गुणवत्ता को मापने के रूप में इसे पढ़ रहा है।
एंड्रयू टी फिनेल

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

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

1
@whatsisname मैं बहुत खुश हूं कि कोई और है जो समझता है। आपकी प्रतिक्रियाओं को अधिक सुरुचिपूर्ण ढंग से और सटीक रूप से लिखा गया है, जितना मैं कभी भी प्रयास कर सकता था। कथन with systems that exist to justify and require themselves rather than being a means to an end to ensure quality productsबिल्कुल वही है जो मैं वर्णन करने का प्रयास कर रहा था। मेरे लिए मेरे शब्द खोजने के लिए धन्यवाद। मैं वास्तव में इसका मतलब है। हमें एक प्रक्रिया का पालन करने के विचार से गुणवत्ता को प्रेरित करने के विचार को अलग करना होगा क्योंकि वे समान नहीं हैं। यही कारण है कि हमारे पास QA, Stackoverflow, और बहुत क्षमाशील ग्राहक हैं।
एंड्रयू टी फिनेल

14

अपडेट करें

जोर देने के लिए उद्धरण में मेरी प्रतिक्रिया:

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

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

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

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

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

इसे कभी भी किसी भी मानक में ठीक से कैसे व्यक्त किया जा सकता है? एक मानक तब तक उपयोगी नहीं होता जब तक इसे लगातार और निष्पक्ष रूप से लागू नहीं किया जा सकता है, जहां निष्पक्षता भावनात्मकता के बारे में अधिक है, भावनात्मक नहीं है।

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

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

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

मुझे लगता है कि इन चर्चाओं में कुछ छूट गया है, वह यह है कि Future You भी इस परियोजना के लिए एक डेवलपर है। मूल्य के बारे में पूछने पर, कल आप भी एक व्यक्ति हैं जो टिप्पणी से मूल्य प्राप्त कर सकते हैं। तो टीम का आकार, मेरी राय में कोई फर्क नहीं पड़ता। टीम का अनुभव मायने नहीं रखता है, यह अक्सर बदलता है।

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


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

हमारे पास दो प्रकार की टिप्पणियां हैं:

मशीन पठनीय टिप्पणियाँ

टिप्पणी शैली जैसे कि Javadoc, JSDoc, Doxygen इत्यादि सभी सार्वजनिक इंटरफ़ेस पर टिप्पणी करने के तरीके हैं, जो कोड प्रदान करता है। वह इंटरफ़ेस केवल एकल अन्य डेवलपर (दो व्यक्ति टीम के लिए मालिकाना कोड), डेवलपर्स की एक अज्ञात संख्या (जैसे जेएमएस), या पूरे विभाग के लिए उपयोग किया जा सकता है। इस कोड को एक स्वचालित प्रक्रिया द्वारा पढ़ा जा सकता है जो फिर उन टिप्पणियों, अला HTML, पीडीएफ, और ऐसे पढ़ने का एक अलग तरीका पैदा करता है।

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

मैं कुछ ऐसा कर रहा हूं जो पागल लग रहा है, लेकिन यह वास्तव में नहीं है

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

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

टिप्पणियाँ पर भरोसा नहीं किया जा सकता है

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

यह असिन सुन सकता है, लेकिन मेरे साथ सहन कर सकता है। इन दो लाइनों में से कौन सा वास्तव में मायने रखता है?

// We don't divide by 0 in order to stop crashes.

return 1 / n;

इस उदाहरण में यह सब मायने रखता है कि हमें इस बात का कोई पता नहीं है कि 'n' क्या है, n 0 के लिए कोई चेक नहीं है और अगर वहाँ भी था, तो कुछ भी नहीं है। डेवलपर को n = 00. के लिए चेक डालने से रोकता है । इस प्रकार, टिप्पणी बेकार है और स्वचालित कुछ भी कभी भी इसे पकड़ सकता है। कोई भी मानक इसे पकड़ नहीं सकता है। टिप्पणी, जबकि सुंदर (कुछ को) उत्पाद के परिणाम पर कोई असर नहीं है।

परीक्षण संचालित विकास

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

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

प्रलेखन अच्छा है जब आप यह पता लगाने की कोशिश कर रहे हैं कि किसी ने कुछ निश्चित तरीके से क्या किया है, हालांकि, मैंने उन वर्षों के माध्यम से पाया है कि प्रलेखन आमतौर पर यह समझाने के लिए उपयोग किया जाता है कि कुछ 'चतुर' क्यों किया गया था, जब इसे वास्तव में ज़रूरत नहीं थी इस तरह लिखा जाना।

निष्कर्ष

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

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

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

टिप्पणियों का जीवन बचाने से कोई लेना-देना नहीं है। टिप्पणियाँ मनुष्यों के लिए होती हैं, मनुष्य टिप्पणी करते समय भी गलतियाँ करते हैं। मनुष्यों पर भरोसा मत करो। एर्गो, टिप्पणियों पर भरोसा न करें। टिप्पणियाँ आपके समाधान नहीं हैं।


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

1
यहाँ, हमारे पास एक टाइमकीपर था जो हमारे लिए दैनिक रिपोर्ट चाहता था कि उसने क्या किया ताकि वह हमारे काम का अनुकूलन कर सके। किसी भी तरह से हम इस बात को लेकर थोड़े क्रोधित थे कि हमें हर दिन उसके फॉर्म को भरने में 15 मिनट का समय लगता है इसलिए हमने अपने लॉग से कचरा भरकर इसे स्वचालित कर दिया।
पूजा २१'१६

1
"हम दुर्घटनाओं को रोकने के लिए 0 से विभाजित नहीं करते हैं" टिप्पणी के साथ एक अतिरिक्त समस्या है। यह स्पष्ट रूप से स्पष्ट नहीं है कि यदि "क्रम में" खंड विभाजन की कार्रवाई पर लागू होता है, या इसकी उपेक्षा के लिए। यदि आप "हम 0 से विभाजित होने से बचते हैं ..." का उपयोग करते हैं तो आप इस अस्पष्टता से बचते हैं। :)
वाइल्डकार्ड

1
"क्रैश को रोकने के लिए शून्य से विभाजित न करें" वास्तव में मुझे उस व्यक्ति की मानसिकता के बारे में बहुत कुछ बताता है जिसने इसे लिखा था। आप दुर्घटनाओं से बचने के लिए कोड नहीं है! आप कोड करते हैं ताकि कोड सही हो, और दुर्घटनाग्रस्त न हो यह सही होने का सिर्फ एक छोटा सा हिस्सा है। यदि इंजेक्शन की दवा की मात्रा शून्य से विभाजित होती है, तो आप 99999 जैसे कुछ डमी मूल्य नहीं लौटाते हैं ...
5

1
@AndrewTFinnell मेरा मतलब है कि यदि आपको कभी-कभी शून्य त्रुटि से एक विभाजन मिलता है, तो "अगर (भाजक == 0) रिटर्न <कुछ> जोड़ते हैं, तो // शून्य से विभाजन से बचें" आपके कोड को और अधिक सही नहीं बनाता है। इसके बजाय आपको यह पता लगाने की आवश्यकता है कि भाजक शून्य क्यों है और इसे ठीक करें। कुछ एल्गोरिदम डिज़ाइन किए गए हैं इसलिए शून्य विभाजक अपरिहार्य है, लेकिन वे अपवाद हैं (और उस स्थिति में आप "परिणाम की गणना नहीं की जा सकती" का मान लौटा सकते हैं)।
20

12

जब आप टिप्पणियों के बारे में बात करते हैं तो दो अलग-अलग चीजें होती हैं। वे समान नहीं हैं, और भेद महत्वपूर्ण है।

दस्तावेज़ीकरण आपको कोड के एक टुकड़े के बाहरी-सामने वाले बिट्स के बारे में बताता है - इसका इंटरफ़ेस।

आमतौर पर टूलींग आपको उन्हें एक 'स्टैंडअलोन' फैशन में पढ़ने की अनुमति देगा, यानी आप एक ही समय में अंतर्निहित कोड नहीं देख रहे हैं।

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

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

सोर्स कोड में टिप्पणियों का एक अलग उद्देश्य है। वे वहाँ स्रोत कोड को देखने वाले लोगों के लिए हैं। वे मुख्य रूप से कार्यान्वयन का वर्णन करते हैं।

टिप्पणियाँ हमेशा अंतर्निहित कोड के बीच पढ़ी जाती हैं।

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

# 'map' outperforms 'for' here by a factor of 10  

// This line works around an obscure bug in IE10, see issue #12053  

-- We are going to recursively find the parents up to and including the root node.
-- We will then calculate the number of steps from leaf node to root node.
-- We first use a WITH clause to get the ID of the root node.

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

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

लेकिन यह उससे भी बदतर है: यदि प्रत्येक पंक्ति में टिप्पणी की जाती है तो एक टिप्पणी का उद्देश्य पराजित होता है। टिप्पणियाँ शोर बन जाती हैं जो कोड को पढ़ना मुश्किल बनाती हैं: स्पष्ट करने के बजाय अस्पष्ट। इसके अलावा, अंधाधुंध टिप्पणी वास्तव में महत्वपूर्ण टिप्पणियों को हाजिर करना कठिन बनाती है।

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

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


सार्वजनिक एपीआई दस्तावेज एक अच्छा बिंदु है, लेकिन मुझे वास्तव में आश्चर्यजनक निर्णय समझाना पसंद है। यह बहुत अच्छा है अगर कम से कम विस्मय के सिद्धांत का उल्लंघन कम से कम औचित्य के साथ आता है। +1
कैंडिड_ओरेंज

1
शोर के रूप में बाहरी टिप्पणियों के लिए +1। शोर को उच्च रखने के लिए संकेत रखें।
15:33 पर sq33G

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

10

आप एक टिप्पणी मानक को संहिताबद्ध नहीं कर सकते, क्योंकि आप नहीं जान सकते कि महत्वपूर्ण टिप्पणी अग्रिम में क्या होगी।

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

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

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

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

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


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

"... जब आप x, y, या z जानते हैं तो यह केवल स्पष्ट है" आप ज्ञान की मात्रा को निर्दिष्ट कर सकते हैं {x, y, z} जो पहले से कुछ स्पष्ट और फिर देखने के लिए पहले से ज्ञात होना चाहिए (तरह यंत्रवत्) आप यह जाँच सकते हैं कि क्या यह वर्तमान कोड के लिए सही है। जहां नहीं है, टिप्पणी जोड़ें।
ट्रिलियन नोव

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

@David Hammen समीक्षा के लिए चुने गए लोग निर्णय लेते हैं? और जब वे चले जाते हैं? यदि नए लोग उसी तरह नहीं सोचते हैं या अंग्रेजी बोलते हैं? अगर 'समीक्षकों' की छुट्टी? आपका सुझाव आइवरी टॉवर के ऊपर कुछ डेवलपर्स डालता है, जिससे असंतोष, अविश्वास और संचार का टूटना होता है। टिप्पणियाँ उन लोगों के लिए अंतर्दृष्टि या स्पष्टीकरण प्रदान करने के लिए हैं जो इसका उपयोग कर सकते हैं। शायद जो जरूरत है, लेकिन मैरी नहीं करता है। जब मैरी समीक्षक होती है तो क्या होता है? या जो? या निशान?
एंड्रयू टी फिनेल

@jmoreno - कोडिंग मानकों में टिप्पणियों के बारे में नियम / दिशानिर्देश नहीं रखने का मतलब है कि प्रोग्रामर को कई स्रोतों को देखना होगा - और उन्हें पता नहीं है कि समीक्षा को वापस आने तक कहाँ देखना है, यह कहना कि टिप्पणियां घटिया हैं। यह सोचना एक गलती है कि कोडिंग मानक में सब कुछ स्वचालित होना चाहिए। उदाहरण के लिए, सार्थक नामों पर नियम स्वचालित नहीं हैं। कम से कम अब तक नहीं। उदाहरण के लिए, x, y, और z, या i, jहै, और kकाफी सार्थक नाम हो सकता है अगर एक एक पत्रिका कागज है कि इसके सूत्रों में वास्तव में उन नामों का इस्तेमाल किया के आधार पर एक वैज्ञानिक एल्गोरिथ्म लागू कर रहा है।
डेविड हैमेन

9

कोड की हर पंक्ति टिप्पणी करें? नहीं

आप जिन अन्य नियमों के बारे में बात करते हैं उनका उद्देश्य इससे बचने के लिए ठीक है।

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

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

मैं कहूंगा कि कोड के अलावा किसी अन्य दस्तावेज की जरूरत नहीं होनी चाहिए।

ऐसी शैलियाँ हैं जो कुल विपरीत जाती हैं, यदि आपको रेखा के बारे में संदेह है तो यह है:

  1. कोड बहुत जटिल है और कोड के भाग के लिए अर्थ अर्थ के साथ नाम के साथ एक फ़ंक्शन में फिर से जोड़ा जाना चाहिए। यह एक जटिल ifया एक एल्गोरिथ्म का एक हिस्सा हो। (या एक चतुर LINQ एक-लाइनर)

  2. यदि इसे सरल नहीं किया जा सकता है, तो आप भाषा के पर्याप्त मुहावरों को नहीं जानते हैं।

(मैं व्यक्तिगत रूप से सख्त नो-कमेंट्स नियम का कट्टरपंथी नहीं हूं, लेकिन मैं इसे एक अच्छी प्रारंभिक मानसिकता के रूप में देखता हूं।)

यह सब देखते हुए क्या यह अच्छा कोडिंग मानकों को लिखना संभव है जो इस विचार को पकड़ते हैं?

प्रक्रिया के लिए के रूप में। हमारे मानक ने समीक्षक को काफी श्रेय दिया। यह मानते हुए कि वे दुर्भावनापूर्ण नहीं हैं यह अच्छा काम करता है।

जब वह पूछता है "चर क्या है o?", तो आप इसका नाम बदलें। यदि वह पूछता है कि यह ब्लॉक क्या करता है, तो रिफ्लेक्टर या टिप्पणी करें। यदि कोई बहस हुई कि क्या कुछ स्पष्ट है या नहीं, यदि समीक्षक नहीं मिला, तो परिभाषा के अनुसार यह नहीं है। बहुत ही कम मौकों पर कुछ दोस्तों से 2 राय जैसा कुछ था।

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

इसके अलावा, कोई निरपेक्षता नहीं थी । हालांकि हम एक छोटे समूह थे। 5 के समूह में सर्वसम्मति ढूंढना आसान है।


2
वेरिएबल्स, क्लासेस और तरीकों को निर्धारित करने के लिए कोड समीक्षाओं का उपयोग करके लोगों को कंपनी, व्यवसाय या कार्यप्रणाली से नफरत करने का सबसे अच्छा तरीका बताया जाता है। कोड समीक्षाओं का उपयोग उन चीजों को लागू करने के तरीके के रूप में नहीं किया जाना चाहिए जो वास्तव में मायने नहीं रखते हैं। एक कोडिंग मानक एक स्वचालित प्रक्रिया के माध्यम से जांच योग्य होना चाहिए। वैरिएबल नाम की लंबाई, सर्कुलर कॉम्प्लेक्सिटी, लॉ ऑफ डेमेटर, वे सभी चीजें हैं, जिन्हें जांचा जा सकता है। अगर किसी ने मुझे 'i' से एक चर का नाम बदलने के लिए indexForThePrepretCollection की तरह कुछ करने के लिए कहा, तो मुझे काम करने के लिए एक और जगह मिलेगी। चर> 3 वर्ण स्वचालित रूप से चेक-इन से पहले जांचे जाते हैं।
एंड्रयू टी फिनेल

3
@AndrewTFinnell मैं नाम रखने के लिए किसी भी प्रोग्रामिंग प्रतिमान में कोड का पालन करना असंभव लिख सकता हूं।
कैंडिड_ओरेंज

2
@AndrewTFinnell खैर, मैं विनम्रता से असहमत हूँ। " हुक्म के लिए कोड समीक्षाओं का उपयोग करना ", मुझे नहीं पता कि आपने इसे कहाँ से निकाला है। मैं चर के साथ कोड पर काम नहीं करना चाहते हैं i, j, kहर जगह के बाद मूल लेखक इस्तीफा। मैं "मानव" जीनोम पर आपकी बात नहीं समझता। मुझे संदेह है कि एक ऐसी भाषा है जहाँ एक ही कथन है, या दो को समझना बहुत कठिन है। जैसा कि मैंने कहा है, मैंने जटिल ifs और LINQवन-लाइनर्स देखे हैं । उन्हें या तो टिप्पणी की जा सकती है या एक अर्थपूर्ण रूप से सार्थक नाम के तहत खंडन किया जा सकता है, मुझे लगता है कि यह आपकी "अच्छी टिप्पणी" है।
luk32

3
@ luk32 मैं असहमत होने के अधिकार का सम्मान करता हूं। मेरी राय में Iteration चर काफी प्रासंगिक हैं। जबकि मैं आपके कथन की भावना को समझता हूं, मेरा मानना ​​है कि बहुत सारी प्रथाएं हैं जो उस भावना को चरम पर ले जाती हैं। क्या हमें वास्तव में कोड की आवश्यकता है जो पढ़ता है: for (int indexForCurrentDatabaseRow = 0; indexForCurrentDatabaseRow < currentUserRecordSetResults.length; indexForCurrentDatabaseRow = indexForCurrentDatabaseRow + 1)बनाम for (int i = 0; i < results.length; i++)? शायद यह वरीयता और / या कोड को देखने में बिताए समय की बात है। अत्यधिक क्रिया के नाम से मुझे बदबू आती है।
एंड्रयू टी फिनेल

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

9

प्रश्न:

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

टिप्पणियों को भाषा पर पाठक को शिक्षित करने की तलाश नहीं करनी चाहिए। एक पाठक को लेखक से बेहतर भाषा को जानना चाहिए, लेकिन लेखक की तुलना में बहुत कम संदर्भ के साथ।

इस कोड के एक पाठक, आपके उदाहरण से, पता होना चाहिए कि exit()आवेदन से बाहर निकल जाएगा - इस प्रकार टिप्पणी को बेमानी बना देगा:

/* Exit the application */
exit();

निरर्थक टिप्पणियां DRY का उल्लंघन हैं, और कोड में बदलाव जरूरी नहीं कि टिप्पणियों को प्रचारित करें, टिप्पणियों को छोड़कर जो यह नहीं दर्शाते हैं कि कोड वास्तव में क्या कर रहा है।

हालाँकि, टिप्पणियां जो बताती हैं कि आप कुछ क्यों कर रहे हैं मूल्यवान हो सकता है - खासकर यदि आप आसानी से कोड में अर्थ को आसानी से संवाद नहीं कर सकते हैं।

पायथन का PEP 8 (सीपीथॉन मानक पुस्तकालय में पायथन के लिए स्टाइल गाइड) इनलाइन टिप्पणियों के लिए निम्नलिखित दिशानिर्देश प्रदान करता है:

इनलाइन टिप्पणियों का संयम से उपयोग करें।

इनलाइन टिप्पणी एक कथन के रूप में उसी पंक्ति पर एक टिप्पणी है। इनलाइन टिप्पणियों को बयान से कम से कम दो स्थानों से अलग किया जाना चाहिए। उन्हें एक # और एक एकल स्थान से शुरू करना चाहिए।

इनलाइन टिप्पणियां अनावश्यक हैं और वास्तव में विचलित करने वाली हैं यदि वे स्पष्ट हैं। ऐसा न करें:

x = x + 1                 # Increment x

लेकिन कभी-कभी, यह उपयोगी है:

x = x + 1                 # Compensate for border

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

border_compensation = 1
compensated_x = x + border_compensation

अपने कोड को स्व-दस्तावेजी बनाना एक नया विचार नहीं है

वास्तविक प्रश्न पर वापस जाएं:

यह सब देखते हुए क्या यह अच्छा कोडिंग मानकों को लिखना संभव है जो इस विचार को पकड़ते हैं?

मेरा मानना ​​है कि PEP 8 मार्गदर्शन और उदाहरण एक अच्छा कोडिंग मानक प्रदर्शित करता है जो इस विचार को दर्शाता है। तो हां, मेरा मानना ​​है कि यह संभव है।


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

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

4

मुझे लगता है कि जब आप इस तरह की टिप्पणी देखते हैं, और मैं इस तरह से खुद को कभी-कभार लिखता हूं, ऐसा इसलिए है क्योंकि लेखक टिप्पणियों में बाहर की ओर लिख रहा है और फिर प्रत्येक टिप्पणी के माध्यम से जा रहा है और लागू कर रहा है।

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

संपादित करें ----

केवल स्पष्ट करने हेतु। मैं टिप्पणी में नहीं मिल रहा हूँ बनाम tdd बनाम इकाई परीक्षण जो सबसे अच्छा है। या प्रति पंक्ति एक टिप्पणी का सुझाव देना एक अच्छा / बुरा है

मैं सिर्फ एक कारण बता रहा हूं कि आप उदाहरण में बात करने की शैली देख सकते हैं।

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

अर्थात टिप्पणियाँ कोड के उद्देश्य को समझाने के लिए हैं, जो एक युक्ति भी है


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

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

6
मुझे यह भी विश्वास है कि इवांस
इवान

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

2
@ जोशसवेल और इवान, हाँ यह कई साल पहले एक तकनीक थी और वास्तव में टीडीडी का पूर्वानुमान था । लेकिन, आप बाद में टिप्पणियों को हटाने के लिए थे! और TDD ने पूरी तरह से इसे कोड बनाने का एक समझदार तरीका मान लिया है जो एक कल्पना से मिलता है।
डेविड अरनो

4

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

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

मेरा # 1 नियम है "स्पष्ट दस्तावेज न दें।" # 2 नियम "स्पष्ट कोड लिखें" है।

सुरक्षा-महत्वपूर्ण कोड के लिए (जिस पर मुझे कभी काम नहीं करना था, भगवान का शुक्र है), यह एक आवश्यक लेकिन पर्याप्त पहले कदम के पास कहीं नहीं है। यहां तक ​​कि यह बताने के लिए भी नीचे आना पड़ सकता है कि किस भाषा की सुविधाओं से बचा जाना चाहिए (मैंने एक से अधिक मानक "" scanf( "%s", input ); किसी भी कारण से उपयोग न करें ") को अनिवार्य रूप से देखा है ।


जाहिर है देखने वाले की नजर में है। और समय सीमा के आधार पर परिवर्तन होता है।
टोनी एनिस

3

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

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

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

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

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


1
महत्वपूर्ण टिप्पणियों पर याद आती है: +1। वाक्य जो शुरू होता है: "वे वर्णन नहीं करते हैं" कुछ पुनर्गठन का उपयोग कर सकते हैं ताकि इसका पालन करना आसान हो सके।
कैंडिड_ऑरेंज

3

IMHO यह दोनों करना चाहिए। हर लाइन पर टिप्पणी करना मूर्खतापूर्ण है, क्योंकि आप लाइनों की तरह हवा करते हैं

  i++;    /* Increment i */

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

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


2
Doxygen टिप्पणी के लिए +1: यह मेरे कोड में doxygen "प्रलेखन" को शामिल करने के लिए मेरी आपत्ति है; समय का 95% यह दोहराता है कि फ़ंक्शन हस्ताक्षर से क्या पहले से ही स्पष्ट है। मैंने भी, अभी तक एक भी डॉक्सीजेन डॉक्यूमेंटेशन नहीं देखा है, जिसकी कीमत कुछ भी हो। उन टिप्पणियों को लिखना तीन बार समय बर्बाद करता है: एक बार टिप्पणियों को लिखने के लिए, एक बार उन्हें फिर से पढ़ने के लिए, और एक बार टिप्पणी सामग्री द्वारा बनाई गई समस्याओं को डीबग करने के लिए।
सेमीस्टर

1
क्या आप खुद का विरोध नहीं कर रहे हैं? मुझे लगता है कि हम दोनों सहमत होंगे कि किसी फ़ंक्शन के लिए यह टिप्पणी करना महत्वपूर्ण है कि यह एक ब्लैक-बॉक्स परिप्रेक्ष्य से क्या करता है - "ये इनपुट अंदर जाते हैं, फ़ंक्शन यह करता है, और ये आउटपुट बाहर आते हैं"। यह फ़ंक्शन लिखने वाले व्यक्ति और फ़ंक्शन का उपयोग करने वाले लोगों के बीच अनुबंध बनाता है। Doxygen का उद्देश्य बस उन टिप्पणियों के प्रारूप को एक तरह से मानकीकृत करना है, जिन्हें पार्स किया जा सकता है और उन्हें खोज योग्य या अनुक्रमणिका बनाया जा सकता है। तो क्यों आप एक "अच्छा टिप्पणी ब्लॉक" चाहेगा लेकिन नहीं यह एक मानक, मानव और मशीन पठनीय प्रारूप में करना चाहते हैं?
ग्राहम

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

मैं इसे नहीं बना रहा हूं - एक कनाडाई आवश्यकता को पूरा करने के लिए, मैंने जिस कंपनी में काम किया था, डेवलपर्स ने एक पूर्व-प्रोसेसर लिखा था जो टिप्पणियों को ओपी के उदाहरण की तरह जोड़ता था। मुझे लगता है कि हमारा "C ADD 1 TO I" या कुछ ऐसा था। यह फोरट्रान था, इसलिए छोरों को "सी लूप से 1 से 10" तक समान रूप से सराहा गया था। कोड बेकार टिप्पणियों के साथ लोड किया गया था। कोड को बनाए रखते हुए मैंने वह सब बकवास हटा दिया। मुझसे किसी ने कभी कुछ नहीं कहा।
टोनी एनिस

2

यह प्रवाह प्रवाह चार्ट वापस लाने का समय है! (वास्तव में नहीं लेकिन एक मिनट पर लटका)

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


मुझे आपको सूचित करने के लिए खेद है कि फ्लोचार्ट कभी नहीं चले गए।
चींटी पी

कोड की तुलना में अच्छी टिप्पणियां अमूर्तता के एक अलग स्तर पर हैं । सुनो सुनो!
कैंडिड_ऑरेंज

1
जबकि यह एक अच्छी सलाह हो सकती है, यह उस प्रश्न को संबोधित करने के लिए प्रतीत नहीं होता है, जो शायद एक वाक्य को छोड़कर था।
ब्रायन ओकले

0

मैं इस प्रश्न का उत्तर दूंगा:

यह सब देखते हुए क्या यह अच्छा कोडिंग मानकों को लिखना संभव है जो इस विचार को पकड़ते हैं?

हाँ। WYSIWYG। एक अच्छा कोडिंग मानक शाब्दिक है " पाठक को स्पष्ट है कि निम्नलिखित कोड क्या करता है और क्यों "।

दूसरे शब्दों में, कोड की पठनीयता के बारे में मेरी कोड समीक्षा टिप्पणी, 1-1, मेरी मानसिक स्थिति से उत्पन्न होती है

मैं, एक पाठक के रूप में, (बेहतर अभी तक, एक न्यूनतम मानक के रूप में, एक कम-अनुभवी लेकिन उचित पाठक का मानसिक मॉडल), निम्नलिखित कोड के उद्देश्य, या काम करने के तरीके को नहीं समझूंगा

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

यह "आपके कोड में व्यावहारिक समस्या के लिए एक विशिष्ट पठनीयता की कमी है" से "आप व्यर्थ मानक का पालन नहीं किया" से प्रवचन को स्थानांतरित करते हैं ।

एक दूसरा मानक जो स्पष्ट किया जाना चाहिए वह है "2am आपातकालीन परीक्षण"।

क्या आपका बैकअप, जो इस कोड के साथ अनुभवी नहीं है, यह पता लगा सकता है कि 2am प्रोडक्शन इमरजेंसी ब्रिज कॉल के दौरान इसे डीबग करते समय कोड के साथ क्या समस्या है, जब आप बिना सेल फोन के चिली चिलीज में छुट्टी पर हैं?

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


0

इस जवाब ने अधिकांश मुद्दों को कवर किया, हालांकि एक महत्वपूर्ण बात है।

मैं एक विचार को तर्ज पर पकड़ना चाहता हूं: प्रत्येक पंक्ति, अनुक्रम, कथन, अनुभाग, संरचना, कार्य, विधि, वर्ग, पैकेज, घटक, कोड के लिए एक टिप्पणी पर विचार करें।

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


1
लेकिन इस तरह के उपकरणों से उत्पन्न "प्रलेखन" कम से कम मेरे अनुभव में है, आम तौर पर बिना किसी दस्तावेज के कम से कम मूल्य का है, क्योंकि यह उपयोगकर्ता को उपयोगी जानकारी प्रदान नहीं करता है (और उन्हें गैर-निकालने का प्रयास करने में समय बर्बाद करने का कारण बनता है। मौजूद जानकारी), लेकिन डेवलपर्स को यह सोचकर मूर्ख बनाते हैं कि उन्होंने अपने कोड को ठीक से प्रलेखित किया है।
जेमस्क्फ

@jamesqf हां, जब आधे कार्य प्रलेखित नहीं हैं, और अन्य आधे बुरी तरह से। हालाँकि, डॉक्‍टर काफी अच्‍छे दस्‍तावेज उत्‍पन्‍न कर सकते हैं, यह मानते हुए कि डेवलपर्स ने उनके कार्यों, कक्षाओं आदि के बारे में ठीक से टिप्‍पणी की है
Bћовић

-1

मौजूदा उत्तरों में से कई अच्छी तरह से विस्तृत हैं, लेकिन मुझे उत्तर देना महत्वपूर्ण लगा:

... [टिप्पणियाँ] जो एक सहकर्मी की समीक्षा में प्रासंगिक होगी, लेकिन एक नासमझ चेकलिस्ट गतिविधि में नहीं बदलेगी ...

मेरे लिए केवल वही टिप्पणियाँ जो एक मानक हो सकती हैं, उनका उत्तर यह पूछकर दिया जा सकता है कि जब वे गायब हों तो क्या टिप्पणियां देखी जा सकती हैं । दूसरे शब्दों में: आईडीई या प्रलेखन सॉफ्टवेयर द्वारा उपयोग की जाने वाली टिप्पणियाँ।

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

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