मेरा ग्राहक मेरे वर्तमान प्रोजेक्ट में 25% टिप्पणियां चाहता है, कैसे प्रतिक्रिया दें? [बन्द है]


96

जूनियर डेवलपर यहाँ।

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

मैंने पिछले अनुप्रयोगों के कोड की जाँच की और यहाँ मेरे अवलोकन हैं:

  • प्रत्येक फ़ाइल एक टिप्पणी ब्लॉक के साथ शुरू होती है (पैकेज, अंतिम अद्यतन तिथि, मेरी कंपनी और कॉपीराइट का नाम)
  • सभी चर उनके नाम के साथ टिप्पणी की जाती है // nameOfCustomer public String nameOfCustomer

  • सभी गेटर्स और सेटर्स पर टिप्पणी की जाती है

  • बहुत कम उपयोगी टिप्पणियाँ

ऐसा लगता है कि डेवलपर्स सिर्फ इतनी टिप्पणियां करते हैं कि वे गुणवत्ता और उपयोगिता की परवाह किए बिना उस 25% की सीमा तक पहुंच सकें। मेरी कंपनी मुझसे कहती है कि "हम ऐसा करते हैं जैसा ग्राहक चाहते हैं"।

मैंने इस बारे में क्लाइंट से सीधे बात नहीं की। यहाँ अब तक मेरे तर्क हैं:

  • पढ़ने के लिए और लिखने के लिए बेकार समय (समय की बर्बादी)
  • टिप्पणियां कभी-कभी अपडेट नहीं की जाती हैं (भ्रम का स्रोत)
  • डेवलपर्स वास्तविक उपयोगी टिप्पणियों का उपयोग या भरोसा करने की कम संभावना रखते हैं

इस विषय पर आपकी क्या सलाह है? मुझे स्थिति को कैसे संभालना चाहिए?


162
क्या बकवास है। हालाँकि, यदि ग्राहक यही चाहता है और ग्राहक उसे प्राप्त करने के लिए आपको अच्छा पैसा दे रहा है, तो आप उसे दे।
रॉबर्ट हार्वे

20
25% लाइनें (मतलब कि आपने कोड के समान लाइन पर कभी टिप्पणी नहीं की) या 25% बाइट्स ?
रॉनजॉन


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

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

जवाबों:


115

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

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

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

ठीक है, तो संवाद कहाँ जाता है अगर वह शुरुआती बिंदु है? संवाद का अगला भाग इस प्रकार है:

  1. मुझे उम्मीद है कि यह एक गंभीर अतिरिक्त प्रयास होगा, संभवतः परियोजना के दूसरे चरण में, यह उस उपकरण के उत्पादन से ऊपर और परे है जो वे काम करने के बारे में परवाह करते हैं। इस प्रक्रिया पर चर्चा करने के लिए कई मिनटों की चर्चा हो सकती है और यह अतिरिक्त काम क्यों है, लेकिन मैं इसे यहाँ छोड़ जा रहा हूं क्योंकि एक पेशेवर प्रोग्रामर के रूप में मुझे उम्मीद है कि आपको पता है कि अच्छी टिप्पणी करना कितना कठिन है।
  2. "एक गंभीर अतिरिक्त प्रयास" का मतलब है कि हमें एक लंबे समय के बजट और अधिक से अधिक मौद्रिक बजट की आवश्यकता हो सकती है; या हमें सुविधा बजट को कम करने की आवश्यकता हो सकती है; याहमें टिप्पणी की गुणवत्ता और मात्रा पर समझौता करने की आवश्यकता हो सकती है। यह हिस्सा थोड़ी बातचीत का है। लेकिन मेरी राय में, आपको इस अतिरिक्त कार्य को करने की लागतों के बारे में बहुत अधिक सामने होना चाहिए, और यह सुनिश्चित करना चाहिए कि यह क्लाइंट के लिए इतनी महत्वपूर्ण विशेषता है कि वे इन लागतों को लेने के लिए तैयार हैं। और अगर वे हैं - महान! आपको अतिरिक्त समय और पैसा मिलता है, और उन्हें उच्च-गुणवत्ता वाली टिप्पणियां मिलती हैं। हर कोई जीतता है। और अगर यह पता चला कि टिप्पणी करने की सुविधा उनके लिए इतनी महत्वपूर्ण नहीं है कि वे विगेट्स को फेल करने की क्षमता खोने के लिए तैयार हैं या 20x6 के अंत में अंतिम समय सीमा तक जाने की इच्छा रखते हैं, तो हर कोई फिर से जीतता है: उन्हें वह उत्पाद मिलता है चाहते हैं, और आपको उच्च गुणवत्ता वाली टिप्पणियाँ बनाने के लिए अतिरिक्त प्रयास खर्च करने की आवश्यकता नहीं है।

यहाँ मुझे लगता है कि संवाद नहीं जाना चाहिए :

  1. कम-गुणवत्ता वाली टिप्पणियों के साथ ग्राहक को धमकी न दें। उन्हें आपकी मदद करने के स्तर को चुनने में मदद करें जो वे खर्च करना चाहते हैं और इसके लिए वे भुगतान करने को तैयार हैं। उन्हें 25% टिप्पणियों का वादा न करें और फिर उन्हें सूचित करें कि आप इस वादा को परियोजना के निर्माण के बाद यादृच्छिकता से ऑटोगेनरिंग द्वारा वितरित करने का इरादा रखते हैं।
  2. अपनी योजनाओं को मत छिपाओ। उन्हें 25% टिप्पणियों का वादा न करें, और फिर उन्हें बताए बिना यादृच्छिकता को स्वतःपूर्ण करें कि आप क्या करने जा रहे हैं। जब वे नोटिस करते हैं (यदि नहीं), तो आप दोनों बड़े समय खो देते हैं: वे उस उत्पाद से नाखुश हैं जो उन्हें मिला है, और आपको नकारात्मक शब्द-इन-मुंह मिलता है।
  3. उन्हें समझाने की कोशिश मत करो वे टिप्पणी नहीं करना चाहते हैं। वे स्पष्ट रूप से टिप्पणी चाहते हैं। विभिन्न दृष्टिकोणों के व्यापार की चर्चा करें: हाँ! कोडबेस को नवागंतुक के अनुकूल बनाने के वैकल्पिक तरीकों पर चर्चा करें: हाँ! उन्हें बताएं कि वे नहीं जानते कि वे क्या चाहते हैं: एह, नहीं। आप उनके साथ काम करना चाहते हैं ताकि वे उन्हें प्राप्त कर सकें जो वे चाहते हैं; तो समझें कि वह क्या है और यह पता लगाना कि उनके द्वारा स्वीकृत बजट में उन तक पहुंचाना कितना अच्छा है, वे उन विशेषताओं को प्राथमिकता देते हैं जिनकी वे परवाह करते हैं यदि उनके पास संसाधन अपर्याप्त हैं।
  4. इस बारे में कोई बहाना मत बनाओ कि कितनी कठिन टिप्पणियां लिखनी हैं। लेखन कोड कठिन है; डिबगिंग कोड कठिन है; टिप्पणी लिखना कठिन है। यदि यह आसान था, तो वे आपको काम पर नहीं रखेंगे। बस शिकायतों को छोड़ें और उस बिंदु तक सीधे पहुंचें, जिसकी वे परवाह करते हैं, अर्थात् अतिरिक्त प्रयास उन्हें कैसे प्रभावित करता है।

3
अच्छा सकारात्मक सवाल :-)
cmaster

9
@ThorstenS। जिस कंपनी के लिए मैं काम करता हूं, वह रक्षा उद्योग के लिए अपने काम की एक सुपरमाजेरिटी करती है। अपनी मानसिक शक्तियों की जाँच करवाना चाहते हैं। इसके अलावा, मैंने कभी नहीं कहा "उनकी इच्छाओं की व्याख्या न करें कि उन्होंने इसे कैसे लिखा है": मैं "25% टिप्पणियों" को एक गंभीर लेकिन आकस्मिक अनुरोध के रूप में मानूंगा - वास्तविक अनुरोध "तकनीकी लेखन का एक बड़ा निकाय" है, और 25% है। प्रयास स्तर के बारे में सिर्फ एक संकेत है कि वे उस शरीर में जाने की उम्मीद करते हैं, संभवतः अनिवार्य रूप से मनमाने ढंग से चुना जाता है, लेकिन फिर भी एक लक्ष्य जिसे आपको याद नहीं करना चाहिए।
डैनियल वैगनर

12
यदि मैं एक प्रोग्रामर को काम पर रख रहा था, तो श्री डैनियल वैगनर उस तरह का लड़का है जिसे मैं किराए पर लेना चाहता हूं।
जो गेयटी

5
यह एक महान जवाब है क्योंकि यह अनुरोध के पत्र के विपरीत अनुरोध के इरादे की पहचान करने और संबोधित करने का प्रयास करता है। IMO यह एक डेवलपर और किसी के बीच का अंतर है जो सिर्फ कोड लिखता है।
जस्टिन ओम्स

6
यह स्पष्ट करना भी अच्छा होगा कि इन टिप्पणियों से रखरखाव लागत में वृद्धि होगी । एक बार बनाने के बाद, उन्हें लगातार अपडेट किया जाना चाहिए , या वे समय और धन की बर्बादी कर सकते हैं। आप इसके लायक); (+1 करने के लिए कल तक प्रतीक्षा की जा रही है ताकि आप वास्तव में प्रतिनिधि मिलता है।)।
jpmc26

83

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

यह कहा जा रहा है, यह बहुत मायने रखता है कि कैसे (यहाँ खराब) गुणवत्ता मानकों को परिभाषित किया गया है:

  • संविदात्मक गुणवत्ता मानक: वितरित कोड का अनुपालन करना चाहिए, अन्यथा यह अनुबंध का उल्लंघन है। कोई विकल्प नहीं।

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

  • ग्राहक के कुछ व्यक्तियों द्वारा परिभाषित तदर्थ मानदंड। यहां आप चर्चा को शामिल कर सकते हैं। आशा है :-)

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

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

लेकिन बुरे के खिलाफ बोलने और ग्राहक का सामना करने के बजाय, आप केवल बेहतर दृष्टिकोण को बढ़ावा दे सकते हैं:

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

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


7
यदि ग्राहक राजा है, तो यह केवल यह दिखाने के लिए जाता है कि ऐसे ग्राहक राजा कितने अक्षम हैं!
स्टीव

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

6
@DavidSchwartz हाँ, निश्चित रूप से। कभी-कभी ग्राहक सोचते हैं कि उन्हें कुछ चाहिए लेकिन वास्तव में दूसरे की आवश्यकता है। परामर्शदाता या उपदेशक को समझाने के लिए, और मेरे उत्तर के 2 / 3rd बिल्कुल इस बारे में हैं। लेकिन यह सब अनुबंध के संदर्भ और प्रदाता और ग्राहक के बीच विश्वास के स्तर पर निर्भर करता है। तो ग्राहक के शासन को राजा को याद दिलाना पड़ता है (वास्तव में मुझे ग्राहकों के साथ कई बार अनुभव हुआ, कि इष्टतम समाधान के बारे में एक लंबी बहस के बाद, मैंने इस वाक्य को उठाया और इससे अचानक बदलाव आया और कुलीन वर्ग के रवैये और सावधान पुनर्विचार; )।
क्रिस्टोफ

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

11
@ हमाटी तथ्य। मैंने एक बार पढ़ने के लिए एक पंक्ति के पीछे मूल इरादे को समझने में काफी समय बिताया,i++; // count down
TKK

18

ग्राहक अपने प्रत्येक सॉफ्टवेयर प्रोजेक्ट में कम से कम 25% टिप्पणियां चाहता है।

क्या ग्राहक वास्तव में 25% टिप्पणियां चाहता है या क्या आपका ग्राहक चाहता है कि आपका कोड यथासंभव वर्णनात्मक हो?

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

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

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

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

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


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

2
@ ग्राहम हां, टिप्पणियां पूरी तरह से अपरिहार्य नहीं हैं। लेकिन, टिप्पणियाँ कोड की तरह हैं: जितना अधिक आप बनाते हैं, उतनी ही अधिक बनाए रखने की आवश्यकता होती है। संक्षिप्त रहने से मुझे विश्वास होता है।
रॉबर्ट डंडन

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

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

12

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

जब ऐसा होता है, तो तर्क दिया जा सकता है कि लोगों के दो समूह गलती पर हैं:

  1. जो लोग सीमा में डालते हैं - स्पष्ट रूप से यह अत्यधिक है और कृत्रिम शोर को जोड़ने के बिना लोगों को अपनी ठीक से गठित जानकारी जमा करने से रोकता है

  2. जिन लोगों ने ऐसी जानकारी प्रस्तुत की, जो ठीक से नहीं बनी थी, तब कृत्रिम शोर मिला जब सिस्टम ने उन्हें वास्तविक पदार्थ जोड़ने के लिए प्रेरित किया

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

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

"लेकिन हम 25% तक कैसे प्राप्त कर सकते हैं?" पदार्थ की वास्तविक टिप्पणी लिखकर। कार्यों के प्रभाव का दस्तावेजीकरण करने के लिए अधिक शब्दों, बेहतर शब्दों का उपयोग करें। अपने स्पष्टीकरण पर विस्तार करें। अधिक विस्तार से किनारे के मामलों का वर्णन करें।

हालांकि, मूल बिंदु पर वापस जाना, ग्राहक आंशिक रूप से यहां भी गलती पर है, क्योंकि "25% स्रोत कोड" बेहद मनमाना है। अंततः, हालांकि, वे ग्राहक हैं, इसलिए इसे सबसे अच्छा बनाते हैं। लेकिन मेरा मतलब है "सर्वश्रेष्ठ"। "सबसे खराब" नहीं, जैसा कि अब तक हो रहा है।


5

मुझे नहीं पता कि इस आवश्यकता के बारे में क्या बड़ा उपद्रव है।

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

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

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

पुनश्च - मानक जावा कंटेनरों के कोड को देखें कि आप कैसे पहुंच सकते हैं, ओह, 70% या तो ...


5

आपके कोड में 25% टिप्पणियां होना एक उत्कृष्ट लक्ष्य है और यह ग्राहक को खुश करता है। अब "i + = 1; // वृद्धि 1" की तरह 25% भद्दे भद्दे कमेंट लिखना आपके नीचे होना चाहिए, इसलिए अपना समय लें, उपयोगी टिप्पणियां लिखें, और उस आनंद का आनंद लें जो आपको वास्तव में कुछ करने के लिए भुगतान किया जाना चाहिए। वैसे भी।


यह एक अच्छा है और साथ ही +1 है। मुझे नहीं पता कि क्या टिप्पणी दर के संदर्भ में एक अच्छा लक्ष्य व्यक्त किया जा सकता है, लेकिन शायद हम में से कई लोग इस '' लक्ष्य तक पहुँचते हैं, बिना किसी उपयोगी तरीके के ... मुझे हाल ही में एक पुराना कोड वापस मिला मैंने अपने कैरियर की शुरुआत में 80 के दशक में लिखा था, इसमें एक अभिनव उच्च प्रदर्शन एल्गोरिथ्म के साथ: इसमें केवल 10% टिप्पणियां हैं, लेकिन रेट्रोएक्टली, काश मैंने इसमें और अधिक डाल दिया होता ;-)
क्रिस्टोफ़

4

हम सभी जानते हैं कि यह एक बकवास आवश्यकता है। दिलचस्प सवाल यह है कि

कैसे प्रतिक्रिया दें?

मैं समस्याओं को स्पष्ट करने में बहुत बड़ा विश्वासी हूँ। यहां मैं इस तथ्य का उपयोग करूंगा कि धन वार्ता।

मुझे ऐसा करने के लिए कहें और मैं निश्चित रूप से कहूंगा, वह मेरी बोली में 1% जोड़ देगा। ओह, लेकिन यह भविष्य की किसी भी रखरखाव बोली में 20% जोड़ देगा।

केवल एक बार वे पूछते हैं कि मैं उन्हें क्यों सिखाऊंगा कि अच्छे नामों की बात यह है कि टिप्पणी करने की आवश्यकता से बचें।

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


3

हां, मैं मूर्खतापूर्ण नियम से आपकी निराशा को समझता हूं। मैंने बेकार टिप्पणियों के साथ बहुत सारे कार्यक्रम पढ़े हैं

x = x + 1; // add 1 to x

और मैं अपने आप से कहता हूँ, इसलिए कि प्लस चिन्ह का क्या मतलब है !! वाह, मुझे बताने के लिए धन्यवाद, मुझे यह नहीं पता था।

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

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

यह एक बहुत ही दुर्लभ मामला होगा, यह मानते हुए कि यह मेरे ऊपर था, मैं एक अनुबंध खो दूंगा क्योंकि मुझे लगा कि आवश्यकताओं की कल्पना की गई थी।

इस बात को ध्यान में रखें कि आपकी कंपनी 25% नियम का आविष्कार करने वाले लोगों के साथ बातचीत कर रही है या नहीं। यह उन पर उच्चतर से लगाया गया नियम हो सकता है।

मैं पांच संभावित प्रतिक्रियाएं देख रहा हूं:

एक। इस बारे में बहस करने के लिए अपने बॉस या जो भी मुवक्किल से बातचीत कर रहा है उसे मना लें। बाधाओं यह कुछ भी नहीं पूरा करेंगे, लेकिन आप कोशिश कर सकते हैं।

दो। इसे करने से मना करें। यह संभवतः आपको निकाल दिया जाएगा, या यदि कंपनी आपसे सहमत है, तो आप अनुबंध को खो देंगे। यह अनुत्पादक लगता है।

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

/*
GetFoo function
Parameters:
  name: String, contains name
  num: int, the number
  add_date: date, the date added
Returns:
  foo code: int
*/
int GetFoo(String name, int num, Date add_date)

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

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

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

MOVE IA010 TO WS124

और उन्होंने कहा कि "प्रलेखन" की एक पंक्ति उत्पन्न होगी

COPY CUSTOMER NAME IN INPUT RECORD TO CUSTOMER-NAME IN WORKING STORAGE

वैसे भी, कोई निश्चित रूप से समान रूप से बेकार दस्तावेज को आसानी से उत्पन्न करने के लिए एक कार्यक्रम लिख सकता है। जैसी लाइन पढ़ो

a=b+c

और टिप्पणी उत्पन्न करें

// add b to c and save result in a

आदि।

पांच। मूर्खतापूर्ण शासन का सबसे अच्छा बनाओ। उपयोगी और सार्थक टिप्पणी लिखने का प्रयास करें। अरे, यह एक अच्छा व्यायाम हो सकता है।

ओह, वैसे, क्या मैं यह जोड़ सकता हूं कि आप हमेशा मीट्रिक खेल सकते हैं।

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

x=x+4;

इसके बजाय मैं लिखूंगा:

x=x+1;
x=x+1;
x=x+1;
x=x+1;

लूप्स? इसे भूल जाओ, मैं कोड को दस बार कॉपी और पेस्ट करूँगा। आदि।

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


2

मनमाने ढंग से मैट्रिक्स भी कई परियोजनाओं में जीवन का एक तथ्य लगता है ...

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

टिप्पणियों को कोड में जोड़ना चाहिए, और समझाएं कि क्या चल रहा है (और कोड को दोहराएं नहीं!)।

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


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

2

लघु अवधि के उपचारों में आप वास्तव में कुछ भी नहीं कर सकते हैं। इसके साथ जाओ।

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

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

किसी भी परिस्थिति में आपको क्लाइंट की अनुमति के बिना इसके खिलाफ नहीं जाना चाहिए।


2

मैं यहां अपने साथी प्रोग्रामरों द्वारा प्रदर्शित कल्पना की कमी से निराश हूं।

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

यह मुझे बेवकूफ या हास्यास्पद बिल्कुल नहीं लगता है। आवश्यकताओं को लिखने वाले लोग सबसे अधिक संभावना प्रोग्रामर नहीं हैं। उन्हें पहले के प्रोजेक्ट के साथ बुरा अनुभव रहा होगा। उनके रखरखाव के लोग शिकायत कर रहे हैं: "इस गंदगी में से कोई भी दस्तावेज नहीं है!"। यह कानों में बज रहा है क्योंकि वे अगली परियोजना के लिए नई आवश्यकताएं लिखते हैं।

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

अंत में, यह 21% या 29% हो, कोई परवाह नहीं करेगा। क्लाइंट के पास आपके सामान की समीक्षा कुछ स्वतंत्र डेवलपर द्वारा की जाएगी और वह बेहतर समझेगा कि आपने क्या किया।


1
प्रश्न निश्चित रूप से साबित करता है कि लक्ष्य के रूप में एक टिप्पणी दर व्यक्त करना बैकफायर होगा। यह ग्राहक के लिए अधिक प्रभावी होगा कि वह गोल गोल के रूप में हो जो कोड किसी अन्य डेवलपर (टीम में? बाहर से समझ में आए? किस पृष्ठभूमि के ज्ञान और कौशल के साथ?) और 25% को एक (लचीले) दिशानिर्देश के रूप में देना होगा। इसे इस तरह से व्यक्त करना ठेकेदारों द्वारा बेहतर समझा जा सकता था, और स्वच्छ कोड जैसे बेहतर विकल्पों को प्रोत्साहित किया।
क्रिस्टोफ़

0

मैं ऐसे कई प्रोग्रामर्स से मिला हूं, जो यह नहीं समझते हैं कि लोग कैसे मौजूद हैं जो वर्तमान में इस प्रोजेक्ट पर काम नहीं करते हैं।

उनके लिए वह सब कुछ है जो वे जानते हैं, आईएस हर किसी के द्वारा जाना जाता है।

यदि कोई वर्तमान में किसी को भी नहीं जानता है तो वे जानते हैं कि वे लोग उनके लिए "बेवकूफ" हैं।

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

वे 99% समय बेकार टिप्पणी लिख सकते हैं, लेकिन कभी-कभी वे वास्तव में एक चीज़ लिख सकते हैं जो "हर कोई जानता है", और टीम पर कोई भी व्यक्ति वास्तव में बग की तलाश में 16 घंटे नहीं बिता सकता है (जो किसी ने हल किया है) लेकिन फिर एक अन्य कारण से पूर्ववत था) जो उस बिंदु पर एक टिप्पणी के साथ स्पष्ट होगा।

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


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