कोड टिप्पणियों में पीरियड्स / फुल स्टॉप्स पर आपके क्या विचार हैं? [बन्द है]

Question

मैंने इसे एसओ टैवर्न में पूछा , इसलिए मैं यहां प्रश्न पोस्ट कर रहा हूं। मुझे यह एक दिलचस्प सवाल लगा। (बेशक यह एसओ पर नहीं है, लेकिन मुझे लगता है कि यह यहाँ ठीक है।)

क्या आप अपने कोड टिप्पणियों में अवधि (या, जैसा कि ओपी ने लिखा है, "पूर्ण विराम") जोड़ते हैं?

इसे प्रासंगिक बनाए रखने के लिए, क्यों ?

Comments

SOmetimes मैं करता हूं और कभी-कभी मैं नहीं करता। यह टिप्पणियों पर निर्भर करता है और क्या पढ़ना आसान बनाता है।

— टिम

Answer 1

पूर्ण विराम वाक्यों को समाप्त करने के लिए है, लेकिन यदि एक टिप्पणी में कोड से घिरे केवल एक वाक्य शामिल है, तो मेरी राय में पूर्ण विराम आवश्यक नहीं है। कभी-कभी मैं भी पहले अक्षर को बड़ा नहीं करता। दूसरी ओर एक विस्तृत बहुस्तरीय टिप्पणी, पूर्ण विराम चिह्न की आवश्यकता है।

// This function returns an average of two integers. Note that it may
// return an irrelevant result if the sum of a and b exceeds the int
// boundaries.

int avg(int a, int b)   // make it static maybe?
{
    // A better algorithm is needed that never overflows
    return (a + b) / 2; 
}

Comments

+1। यह मेरी टिप्पणी की शैली की तरह लग रहा है यह मुझे एक झूठी देजा वू दिया। :)

— बॉबी टेबल्स

नहीं, पूर्ण विराम वाक्यों के अंत को चिह्नित करने के लिए है। यह अप्रासंगिक है कि क्या आपके पास एक या कई हैं।

— रूक

<joke> क्या यह

— अंतर

@ यार: एक औसत हमेशा ए और बी के बीच होता है, जिसकी परिभाषा हमेशा सीमाओं के भीतर होती है, है ना? ;)

— मोज़ुबा

मेरे सभी तार ख़त्म हो गए हैं, इसलिए एक उचित टिप्पणी हमेशा '0' के साथ समाप्त होनी चाहिए। आप नहीं चाहते कि अगला आदमी आपके कोड को देखकर अपने दिमाग के अंत को पढ़े?

— कोडेक्सअर्बनम

Answer 2

हां, क्योंकि टिप्पणियां अंग्रेजी में हैं, और उचित अंग्रेजी विराम चिह्न का उपयोग करती है।

Comments

पाठ संदेशों के बारे में कैसे?

— मोशे

@Moshe, पाठ संदेश शायद ही उचित अंग्रेजी हैं।

— डोमिनिक मैकडोनेल

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

— cjmUK

@cjmUK, Lol, हाँ और इसलिए मैं। मुझे लगा कि मोश का मतलब यह था कि हम विराम चिह्नों का उपयोग नहीं करेंगे, क्योंकि मुझे नियमित रूप से "wd b gr8 cu वहाँ अलविदा" जैसे संदेश मिलते हैं जो मुझे दीवार तक ले जाते हैं

— डोमिनिक मैकडॉनेल

I nu wot u ment im im wiv u all da way

— cjmUK

Answer 3

क्या आप अपने कोड टिप्पणियों में अवधि (या, जैसा कि ओपी ने लिखा है, "पूर्ण विराम") जोड़ते हैं?

इसे प्रासंगिक बनाए रखने के लिए, क्यों?

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

स्रोत कोड सामान्य पाठ नहीं है, और इसलिए हम इसके लिए विभिन्न नियमों का उपयोग करते हैं। सरल ;-)

Comments

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

— लेनीप्रोग्रामर्स

@ Lenny222 - यहाँ आप क्या पूछ रहे हैं यह निश्चित नहीं है। ईमेल सामान्य पाठ की तरह लिखे जाने चाहिए; जैसे आप कहते हैं कि आप एक पत्र लिख रहे हैं। वे वास्तव में कैसे लिखे गए हैं (और एसएमएस, ओह बॉय, मुझे एसएमएस पर शुरू न करें :) स्रोत कोड सामान्य पाठ के समान नियमों के अधीन नहीं है, क्योंकि इसके अपने सिंटैक्स नियम हैं।

— Rook

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

— लेनीप्रोग्रामर्स

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

— रूक

हां, मुझे लगता है कि हम एक दूसरे को बिना जाने समझे सहमत हैं। ;)

— लेन्नीप्रोग्रामर्स

Answer 4

यदि आप टिप्पणी लिखते हैं, तो उन्हें उम्मीद है कि वे अंग्रेजी में लिखे जाएंगे। मामले के मामले में, किसी को ठीक से पंचर होना चाहिए। अन्यथा करना आलसी होगा।

Comments

अवधि एक वाक्य के अंत के लिए होती है। जरूरी नहीं कि टिप्पणियाँ पूर्ण वाक्य हों।

— जॉन बी। लाम्बे

टिप्पणियाँ, सामान्य तौर पर, वाक्य होने चाहिए। यदि नहीं, तो मुझे पूछना चाहिए कि क्यों नहीं। यदि आपकी टिप्पणियाँ इतनी कम हैं कि वे वाक्य नहीं हैं, तो क्या वे शायद स्पष्ट हैं और इसलिए बहुत ही कम हैं?

— जल्दी_अगला

Answer 5

अगर मैं एक पूर्ण वाक्य (या अधिक) लिखता हूं, तो हां। अगर मैं नहीं, तो कभी-कभी नहीं, लेकिन आमतौर पर अभी भी हाँ।

मैं भी कभी-कभी पागल हो जाता हूं और विस्मयादिबोधक अंक, प्रश्न चिह्न, आदि का उपयोग करता हूं;

क्यों के लिए, यह आंशिक रूप से है क्योंकि मैं सिर्फ उस तरह से और आंशिक रूप से हूँ क्योंकि मुझे लगता है कि उचित विराम चिह्न बहुत स्पष्टता जोड़ सकते हैं।

Comments

यदि आप प्रश्नवाचक चिह्न का उपयोग कर रहे हैं, तो क्या आप अपना स्वयं का कोड समझते हैं?

— मोशे

@Moshe: वे आम तौर पर TODOs में होते हैं जब मैं अभी तक पूरी तरह से अपने कोड को नहीं समझ सकता।

— एडम लेअर

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

— cjmUK

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

— लेनीप्रोग्रामर्स

Answer 6

अन्य उत्तरों और उनकी लोकप्रियता ने यह स्पष्ट कर दिया है कि पूर्ण स्टॉप को लंबे समय तक टिप्पणियों में अच्छी तरह से सराहना की जाती है, और शायद एक-लाइनर्स में बचा जा सकता है।

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

    // Though loop is labor-intensive, performance is fine with with 95K cases!!!

तथा

    // This code really sucks!

दूसरी ओर, प्रश्न चिह्न कभी-कभी बहुत उपयोगी होते हैं:

    // TODO: What does Crojpler.bway() actually do?

Answer 7

निर्भर करता है। अगर मैं एक बड़ा, उचित पैराग्राफ लिखता हूं, जिसमें बताया गया है कि कोड का एक ब्लॉक क्या करता है, तो मैं इसे ठीक से लिखता हूं, जैसे कि उचित लेखन का कोई अन्य टुकड़ा। OTOH, जब मैं कोड की एक पंक्ति पर टिप्पणी करता हूं, तब मैं नहीं करता।

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

मेरे कोड से वास्तविक उदाहरण:

त्वरित टिप्पणी टिप्पणी:

// check for vk_enter

"उचित" विधि प्रलेखन:

// This method sets up a workspace tab with the given name. Each MDI window has a parent
// workspace specified when it's saved. The code which loads each MDI window then point it to
// the correct workspace.

Comments

.NET डेवलपर, एह? ;-)

— मोशे

@Moshe: वास्तव में जावा। यह एक बहुत बड़े और जटिल एप्लेट से कोड है, मूल रूप से डेस्कटॉप स्विंग ऐप की तरह है सिवाय इसके कि यह ब्राउज़र में चलता है। :)

— बॉबी टेबल्स

हालांकि मैं एमडीआई एक .NET टर्म है।

— मोशे

@ मोशे: नाह, यह सामान्य है ( en.wikipedia.org/wiki/Multiple_document_bface )।

— बॉबी टेबल्स

Answer 8

हां, मुझे लगता है कि इस तरह से आप एक अच्छा कोडिंग कन्वेंशन बनाते हैं और यह आपके कोड की समीक्षा करने वाले किसी तीसरे व्यक्ति के लिए एक साफ पढ़ने योग्य कोड भी बनाता है।

Comments

एक दूसरे व्यक्ति के बारे में क्या?

— १

Answer 9

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

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