क्या अस्थायी वर्कअराउंड के लिए विधि नाम में बग नंबर शामिल करना खराब अभ्यास माना जाता है?

Question

मेरा सहकर्मी जो एक वरिष्ठ व्यक्ति है, मुझे एक कोड समीक्षा पर रोक रहा है क्योंकि वह मुझे एक विधि 'PerformSqlClient216147Workaround' नाम देना चाहता है क्योंकि यह कुछ दोष ### के लिए एक समाधान है। अब, मेरा विधि नाम का प्रस्ताव PerformRightExpressionCast की तरह कुछ है जो वास्तव में क्या विधि का वर्णन करने के लिए जाता है। उनकी दलीलें इस प्रकार हैं: "वैसे तो इस पद्धति का उपयोग केवल इस मामले के लिए समाधान के रूप में किया जाता है, और कहीं नहीं।"

क्या अस्थायी वर्कअराउंड के लिए विधि के नाम के अंदर बग संख्या को बुरा व्यवहार माना जाएगा?

Comments

बस एक स्पष्टीकरण: दोष ### SqlClient नामक एक बाहरी घटक में है, यह 2008 में दायर किया गया था, यह शायद जल्द ही तय नहीं होगा और यह हमारी शक्ति से बाहर है, इसलिए यह विधि एक डिजाइन का एक हिस्सा है " वर्क-अराउंड "वो इश्यू ...

— Bojan

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

— maple_shaft

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

— user16764

@maple_shaft - प्रश्न पर उत्कृष्ट सहेजें-संपादित करें।

बग #s टिप्पणियों और संस्करण नियंत्रण प्रतिबद्ध नोटों के लिए हैं, विधि के नाम नहीं। आपके सहकर्मी को थप्पड़ मारना चाहिए।

— एरिक रेपेने

Answer 1

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

/**
 * Cast given right-hand SQL expression.
 *
 * Note: This is a workaround for an SQL client defect (#216147).
 */
public void CastRightExpression(SqlExpression rightExpression)
{
    ...
}

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

Comments

दस्तावेज़ की टिप्पणी में बग के प्रत्यक्ष http लिंक होने से यह एक अच्छा विचार होगा। आप अपने स्वयं के एनोटेशन को भी परिभाषित कर सकते हैं@Workaround(216147)

— सुल्तान

या @warning This is a temporary hack to...याTODO: fix for ...

— BЈовић

@ सुल्तान - ज़रूर ... दोष डेटाबेस के लिए लिंक देता है जो कुछ वर्षों में मौजूद नहीं हो सकता है। दोष का वर्णन करें, दोष # (और तिथि) डालें, इसके वर्कअराउंड का दस्तावेजीकरण करें लेकिन आंतरिक उपकरणों के लिंक जो कि एक बुरे विचार की तरह बदल सकते हैं।

— रामहुंड

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

— टिम विस्क्रॉफ्ट

कोड (इस मामले में, विधि का नाम) को स्व-दस्तावेज चाहिए कि वह क्या करता है। टिप्पणियों को यह बताना चाहिए कि कोड क्यों मौजूद है या एक निश्चित तरीके से संरचित है।

— हारून कुरथज़ल

Answer 2

कुछ भी अस्थायी फिक्स से अधिक स्थायी नहीं है जो काम करता है।

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

वह जो प्रस्ताव दे रहा है, वह आपके QC को मजबूर कर रहा है और QA सिस्टम में काफी कमी है। दोषों और दोषों को ठीक करना ट्रैकिंग कोड प्रणाली के अंतर्गत आता है, न कि सोर्स कोड। स्रोत कोड परिवर्तनों का अनुरेखण स्रोत नियंत्रण प्रणाली में आता है। इन प्रणालियों के बीच क्रॉस रेफ़रिंग, स्रोत कोड में दोषों का पता लगाने की अनुमति देता है .....

स्रोत कोड आज के लिए है, कल नहीं, और कल नहीं (जैसा कि, आप स्रोत में टाइप नहीं करते हैं कि अगले साल क्या करने की योजना बना रहे हैं) ...

Comments

+1Nothing is more permanent than a temporary fix that works.

— रिएक्टगुलर

"व्यापक रूप से स्वीकार किया जाता है" [उद्धरण वांछित]

@ ग्राहम: क्या यह काफी अच्छा है, या इसे एक प्रतिष्ठित समीक्षा के रूप में एक सहकर्मी की समीक्षा करने, प्रकाशित पत्र प्रकाशित करने की आवश्यकता है .... stackoverflow.com/questions/123936/…

— Mattnz

Answer 3

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

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

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

public IEnumerable<Report> FindReportsByDateOnly(DateTime date)
{
    // The following method replaces FindReportByDate, because of the bug 8247 in the
    // reporting system.
    var dateOnly = new DateTime(date.Year, date.Month, date.Day);
    return this.FindReportByDate(dateOnly);
}

private IEnumerable<Report> FindReportsByDate(DateTime date)
{
    Contract.Requires(date.Hour == 0);
    Contract.Requires(date.Minute == 0);
    Contract.Requires(date.Second == 0);

    // TODO: Do the actual work.
}

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

निष्कर्ष: आपको पता नहीं है कि यह बग किस बारे में है।

एक ही कोड को थोड़े अलग तरीके से लिखा जा सकता है:

public IEnumerable<Report> FindReportsByDateOnly(DateTime date)
{
    // The reporting system we actually use is buggy when it comes to searching for a report
    // when the DateTime contains not only a date, but also a time.
    // For example, if looking for reports from `new DateTime(2011, 6, 9)` (June 9th, 2011)
    // gives three reports, searching for reports from `new DateTime(2011, 6, 9, 8, 32, 0)`
    // (June 9th, 2011, 8:32 AM) would always return an empty set (instead of isolating the
    // date part, or at least be kind and throw an exception).
    // See also: http://example.com/support/reporting-software/bug/8247
    var dateOnly = new DateTime(date.Year, date.Month, date.Day);
    return this.FindReportsByDate(dateOnly);
}

private IEnumerable<Report> FindReportsByDate(DateTime date)
{
    Contract.Requires(date.Hour == 0);
    Contract.Requires(date.Minute == 0);
    Contract.Requires(date.Second == 0);

    // TODO: Do the actual work.
}

अब आपको इस मुद्दे पर एक स्पष्ट दृष्टिकोण मिलेगा। यहां तक ​​कि अगर यह प्रतीत होता है कि टिप्पणी के अंत में हाइपरटेक्स्ट लिंक पांच साल पहले मर चुका है, तो कोई फर्क नहीं पड़ता, क्योंकि आप अभी भी समझ सकते हैं कि क्यों FindReportsByDateप्रतिस्थापित किया गया था FindReportsByDateOnly।

Comments

ठीक है, हम कहीं जा रहे हैं: आपको क्यों लगता है कि बग कोड के लिए स्रोत कोड एक अच्छी जगह नहीं है?

— Bojan

क्योंकि बग ट्रैकिंग सिस्टम और संस्करण नियंत्रण उसके लिए एक बेहतर जगह है। यह बिल्कुल वैसा ही नहीं है, लेकिन जैसा है: stackoverflow.com/q/123936/240613

— Arseni Mourzenko

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

— बोजन

हालांकि मैं केवल मार्केटिंग करने वाले लोगों को कुछ नया जोड़ने का तर्क दे सकता हूं जो अप्रचलित है।

— मटनज़

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

— दान नीली

Answer 4

मुझे PerformSqlClient216147Workaroundतब अधिक जानकारीपूर्ण लगता है PerformRightExpressionCast। फ़ंक्शन के नाम पर कोई संदेह नहीं है कि यह क्या करता है, यह क्यों करता है या इसके बारे में अधिक जानकारी कैसे प्राप्त करें। यह एक स्पष्ट कार्य है जो स्रोत कोड में खोजना आसान होगा।

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

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

Comments

मुझे विश्वास है कि ऐसा लगता है कि PerformSqlClient216147Workraction दोनों का वर्णन करता है कि विधि क्या करती है और यह मौजूदा का कारण है। मैं इसे अपनी दुकान के लिए विशिष्ट (C #) विशेषता के साथ चिह्नित करूंगा और इसके साथ किया जाऊंगा। न्यूमेरिक्स के नाम में अपनी जगह है ... उम्मीद से ऊपर के रूप में न केवल उस पद्धति का उपयोग करता है जो आपकी दुकान ऐसी चीजों को वर्गीकृत करने के लिए उपयोग करती है। एक चायपत्ती IMHO में तूफान। Btw कि असली त्रुटि कोड है ?? यदि आप वरिष्ठ सहकर्मी हैं, तो संभवतः इस पद की खोज का वंशज मौका है, जो आपके लिए समस्या हो सकती है या नहीं भी ....। ;)

— विस्मयादिबोधक

Answer 5

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

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

Comments

इस विधि की टिप्पणियों में समझाया जाना चाहिए, इसका नाम नहीं।

— आर्सेनी मूरज़ेंको

मैं आम तौर पर आपके उत्तर से सहमत हूं, लेकिन मैं मेनमा से भी सहमत हूं: एक विधि के बारे में मेटा-जानकारी टिप्पणियों में होनी चाहिए, नाम में नहीं।

— रॉबर्ट हार्वे

Answer 6

मुझे लगता है कि आप और वह दोनों ने इस पूरी बात को समानुपात से बाहर कर दिया है।

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

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

किसी भी तरह से, आपके और उसके पास बेहतर चीजें हैं।

Comments

मुद्दा लेना। लेकिन मैं अहंकार की शक्ति को कम नहीं समझूंगा :)

— Bojan

Answer 7

क्या अस्थायी वर्कअराउंड के लिए विधि के नाम के अंदर बग संख्या को बुरा व्यवहार माना जाएगा?

हाँ।

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

यदि मूल रूप से उस वर्ग के सार्वजनिक एपीआई का हिस्सा "दस्तावेज़ / स्थान X में वर्णित ऑपरेशन Y का प्रदर्शन करता है" तो अन्य लोगों की समझने की क्षमता एपीआई पर निर्भर करेगी:

1. उन्हें पता है कि बाहरी प्रलेखन में क्या देखना है

2. उन्हें पता है कि बाहरी दस्तावेज कहां देखना है

3. उन्हें समय और प्रयास और वास्तव में देख रहे हैं।

फिर, आपके विधि नाम में यह भी उल्लेख नहीं है कि इस दोष के लिए "स्थान X" कहां है।

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

बहुत कम से कम, यदि आप जानते हैं कि दोष हमेशा एक ही स्थान पर सुलभ होगा और यह नहीं बदलेगा (जैसे Microsoft दोष संख्या जो पिछले 15 वर्षों से एक ही URL पर है), तो आपको एक लिंक प्रदान करना चाहिए एपीआई के प्रलेखन में मुद्दा।

फिर भी, अन्य दोषों के लिए वर्कअराउंड हो सकते हैं, जो एक वर्ग के एपीआई से अधिक प्रभावित करते हैं। तो तुम क्या करोगे?

कई वर्गों में एक ही दोष संख्या के साथ एपीआई होना ( data = controller.get227726FormattedData(); view.set227726FormattedData(data);वास्तव में आपको बहुत कुछ नहीं बताता है और कोड को अधिक अस्पष्ट बनाता है।

आप यह तय कर सकते हैं कि ऑपरेशन के वर्णनात्मक नाम ( data = controller.getEscapedAndFormattedData(); view.setEscapedAndFormattedData(data);) का उपयोग करके अन्य सभी दोषों को हल कर दिया जाए , सिवाय आपके 216147 दोष के मामले में (जो "कम से कम सर्प्राइज़" के डिजाइन सिद्धांत को तोड़ता है - या यदि आप इसे उस तरह से रखना चाहते हैं, तो यह आपके कोड के "डब्ल्यूटीएफ / एलओसी" का माप बढ़ाता है)।

टीएल; डीआर: खराब अभ्यास! अपने कमरे में जाओ!

Answer 8

एक प्रोग्रामर के प्रमुख लक्ष्य कार्य कोड, और, अभिव्यक्ति की स्पष्टता होना चाहिए।

वर्कअराउंड विधि (.... समाधान) का नामकरण। इस लक्ष्य को प्राप्त करना प्रतीत होगा। उम्मीद है कि कुछ स्तर पर अंतर्निहित समस्या ठीक हो जाएगी और वर्कअराउंड विधि को हटा दिया जाएगा।

Answer 9

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

यदि SqlClient के साथ सहभागिता करने के लिए आपको एक सही एक्सप्रेशन कास्ट करने की आवश्यकता होती है, तो आपके कोड को "performRightExpressionCast ()" पढ़ना चाहिए। आप हमेशा यह बताने के लिए कोड की टिप्पणी कर सकते हैं कि क्यों।

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

मेरे एक सहकर्मी ने एक बार कहा था "जब एक दोष को ठीक किया जाता है, तो कोड को उस तरह से बनाएं जो होना चाहिए था।" जिस तरह से मैं व्याख्या करता हूं कि "कोड को बदलें कि यह कैसे दिखाई देगा यदि यह बग कभी मौजूद नहीं था।"

परिणाम:

1. परिणामस्वरूप, कम कोड।
2. सीधा कोड
3. स्रोत कोड में बग के लिए कम संदर्भ
4. भविष्य के प्रतिगमन का कम जोखिम (एक बार कोड परिवर्तन पूरी तरह से सत्यापित)
5. विश्लेषण करना आसान है क्योंकि डेवलपर्स को सीखने के इतिहास के साथ खुद को बोझ नहीं करना पड़ता है जो अब प्रासंगिक नहीं है।

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

इसलिए यह तय करने के लिए कि क्या आपके तरीके का नाम 'PerformSqlClient216147Workaround' है या नहीं, खुद से पूछें:

1. अगर मुझे कोड लिखने से पहले बग 216147 के बारे में पता था, तो मैंने इसे कैसे संभाला होगा?
2. वर्कअराउंड क्या है? यदि पहले कभी किसी ने इस कोड को नहीं देखा है, तो क्या वे इसे देख पाएंगे? यह कोड कैसे काम करता है, यह जानने के लिए बग ट्रैकिंग सिस्टम की जाँच आवश्यक है?
3. यह कोड कितना अस्थायी है? मेरे अनुभव में, अस्थायी समाधान आमतौर पर स्थायी हो जाते हैं, जैसा कि @mnnz इंगित करता है।