संस्करण नियंत्रण टिप्पणियाँ - भूतकाल या वर्तमान काल [बंद]

Question

संस्करण नियंत्रण टिप्पणियों के लिए अन्य उपयोगकर्ता क्या करते हैं / अनुशंसा करते हैं - अतीत या वर्तमान तनाव?

अर्थात

• परिवर्तित x को y होना चाहिए।
• या
• X को y बदल रहा है ।

Comments

क्या आपका मतलब है "संस्करण नियंत्रण जाँच टिप्पणियाँ"? मैं वास्तविक कोड में परिवर्तन संबंधी दस्तावेज़ीकरण कभी नहीं जोड़ता। यह उसे जकड़ लेता है।

— JohnFx

मैं वास्तव में उलझन में हूँ - अगर @JohnFx सही है, तो यह एक पूरी तरह से अलग सवाल है। मैं व्यक्तिगत रूप से यह नहीं देखता कि @Robert का स्रोत कोड में टिप्पणियों का मतलब क्यों नहीं हो सकता है।

— आर्मंड

FYI करें: मेरा मतलब था चेक-इन, "चेकिंग" नहीं

— जॉनएफएक्स

क्षमा करें - बस भ्रम को दूर करने के लिए मैंने स्रोत कोड में टिप्पणियों के बजाय संस्करण नियंत्रण टिप्पणियां कीं। प्रश्न अद्यतन किया गया है।

— रॉबर्ट डब्ल्यू

इन्हें भी देखें exquisitetweets.com/collection/hugovk/1258 english.stackexchange.com/q/6602/9001 programmers.stackexchange.com/q/157590/25708 stackoverflow.com/q/3580013/724176 stackoverflow.com/q/1753808/ 724176

— ह्यूगो

Answer 1

टिप्पणियों को संदर्भ में पढ़ा जाना चाहिए, इसलिए:

वर्तमान

किसी विधि के ऊपर या कुछ व्यवहार होने से पहले स्रोत टिप्पणियों के लिए:

// This function does X
function doX() { ... }

अतीत

कुछ व्यवहार होने के बाद स्रोत टिप्पणियों के लिए

function doX() {
    widget.doY()
    // did Y to widget to prepare it for Z
    ...
}

और प्रतिबद्ध संदेशों के लिए

फंक्शन X बदल गया

---

मिश्रित उदाहरण:

// This function does X
function doX() {
    widget.doY()
    // did Y to widget to prepare it for Z
    ....
}

Comments

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

— आर्मंड

अब सवाल बदल गया है, यह उत्तर थोड़ा विषय है।

— आर्मंड

Answer 2

अतीत - चूँकि जो भी इसे भविष्य में पढ़ता है वह बदलाव के कृत्य का उल्लेख करेगा जैसा कि अतीत में हुआ है।

"परिवर्तन" के रूप में कुछ रिकॉर्ड करने का अर्थ है कि आप वर्तमान में परिवर्तन करने की प्रक्रिया में हैं और कोड समाप्त नहीं हो सकता है।

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

Answer 3

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

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

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

Comments

+1, हालांकि मुझे लगता है कि संस्करण नियंत्रण टिप्पणियां पिछले तनाव में भी होनी चाहिए। :-)

— एरिक किंग

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

— डोनाल्ड फेलो

प्रतिबद्ध meesages किसी भी तरह से जा सकते हैं। मैं इसे देखना चाहता हूं क्योंकि यह उस समय के कारण के लिए वर्तमान कार्रवाई थी। दिन के अंत में, यह अंग्रेजी का एक ऐसा क्षेत्र है जहां बालों को विभाजित करना संभव नहीं है। यह "ईट्स, शूट्स एंड लीव्स" की तरह नहीं है। en.wikipedia.org/wiki/Eats,_Shoots_%26_Leaves

— बेरिन लॉरिट्स

Answer 4

मैं अनिवार्य वर्तमान काल का उपयोग करता हूं, इसलिए कुछ इस तरह है:

"X" को "y" होने के लिए बदलें

यह गिट डेवलपर्स द्वारा अनुशंसित है:

• शरीर को एक सार्थक वचन देना चाहिए, जो:
  • अनिवार्य, वर्तमान काल का उपयोग करता है: "परिवर्तन", "परिवर्तित" या "परिवर्तन" नहीं।

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

Comments

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

— निक नॉल्ससन

Answer 5

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

Answer 6

कोड टिप्पणियों को पढ़ने के लिए स्वाभाविक होना चाहिए।

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

Answer 7

यदि आप git का उपयोग कर रहे हैं तो कन्वेंशन वर्तमान काल का उपयोग करना है क्योंकि git टूल्स (जैसे मर्ज) के साथ उत्पन्न संदेश वर्तमान काल का उपयोग करते हैं।

Answer 8

आपको भूत काल का उपयोग करना चाहिए।

कारण आप इस सवाल का जवाब दे रहे हैं कि इससे क्या हासिल हुआ? इसे अपने वीसीएस के बारे में बताएं जो आपने किया था:

एबीसी करने के लिए 123 परिवर्तित XYZ प्रतिबद्ध

काउंटर उदाहरण देने के लिए, भविष्य काल का उपयोग करने से यह लगता है कि आप किसी और से इसे करने के लिए कह रहे हैं:

123
एबीसी करने के लिए XYZ बदलें

और वर्तमान काल की आवाज़ों का उपयोग करना, जैसे आप इसके माध्यम से आधे रास्ते पर हैं:

एबीसी करने के लिए 123 चेंजिंग XYZ करें

Answer 9

वर्तमान काल का उपयोग करें: "एक्स को वाई में बदलें," लगभग जैसे कि यह एक स्पष्ट TODO सूची पर एक आइटम था।

सामान्य तौर पर, एक पटकथा की तरह, "होना" और "है" जैसी क्रियाओं से बचें। उदाहरण के लिए, यह "वह चल रहा है" नहीं है, लेकिन "वह चलता है।"

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

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

Answer 10

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

वर्तमान काल ( .ie "यह बदलता है" या "यह बदल रहा है" ) पर टिप्पणियाँ इंगित करती हैं कि दस्तावेज एल्गोरिदम द्वारा संचालित किए जा रहे डेटा का एक टुकड़ा किसी तरह प्रभावित हो रहा है। यही है, यह इंगित करता है कि कोड क्या कर रहा है या डेटा में क्या हेरफेर हो रहा है।

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

कोड के इस ब्लॉक में प्रवेश करने से पहले ही इनपुट को मान्य कर दिया गया है

या

इस कोड के अंत में फाइल करने के लिए डेटा लिखा गया है

पिछले तनाव में टिप्पणियाँ यह भी बता सकती हैं कि कुछ क्यों किया जा रहा है ( यह कार्य लीजेंड डेटाबेस के साथ एक समस्या से निपटने के लिए एक्स और वाई करता है। )

भूत काल में टिप्पणियाँ स्वयं कोड (.ie। X को Y में बदल दिया गया था ) को कोड में मौजूद नहीं होना चाहिए। इसके बजाय उन्हें स्रोत कोड भंडार में संशोधन टिप्पणियों के रूप में मौजूद होना चाहिए।

भविष्य में टिप्पणियों को एक ऐसी स्थिति का संकेत देना चाहिए जिसे मिलना या संबोधित करना आवश्यक है, लेकिन यह कि X या Y कारण के लिए अभी नहीं किया जा रहा है। उदाहरण के लिए:

जब हम अंततः db को स्थानांतरित करते हैं, तो हमें इस तर्क को बदलना होगा

या

TODO: asap, इनपुट का पुनरीक्षण सत्यापन - यह X या Y प्रकार के इनपुट के लिए विफल हो सकता है, इसके लिए बड़े पैमाने पर परिवर्तन की आवश्यकता हो सकती है जिसे अभी लागू नहीं किया जा सकता है।

बाद में TODO प्रकार की टिप्पणियों के लिए, कुछ अन्य प्रकार के प्रलेखन को यह सुनिश्चित करने के लिए मौजूद होना चाहिए कि ऐसे परिवर्तन वास्तव में होते हैं। आखिरी चीज जो आप चाहते हैं कि TODOs समय और स्थान में खो गए हैं: P

इसे नमक के दाने के साथ लें, लेकिन आम तौर पर वे नियम हैं जिनका मैं आमतौर पर अनुसरण करता हूं जब मैं अपनी टिप्पणी करता हूं।

Answer 11

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

• वांछित व्यवहार का वर्णन करने वाली टिप्पणियां एक वर्तमान तनावपूर्ण वाक्य का रूप लेती हैं।

  // Calculate the width of the curve at x height.
  

• कोडिंग में आम विषयों का वर्णन करने के लिए ऑल-कैप कीवर्ड का एक सेट का उपयोग करें (और इसे खोजना आसान बनाएं):

  // NOTE: <This code was written this way for a reason.>
  // TODO: <This code is incomplete. Finish it.>
  // HACK: <This code was written this way for a reason that you won't like.>
  // FIXME: <This code has a known flaw. Fix it.>