क्या आप दूसरे या तीसरे व्यक्ति में टिप्पणियां लिखते हैं?2 या 3 व्यक्ति व्यक्ति टिप्पणियां?
// go somewhere and do something (2nd person comment)
या
// goes somewhere and does something (3rd person comment)
क्या आप दूसरे या तीसरे व्यक्ति में टिप्पणियां लिखते हैं?2 या 3 व्यक्ति व्यक्ति टिप्पणियां?
// go somewhere and do something (2nd person comment)
या
// goes somewhere and does something (3rd person comment)
निश्चित रूप से 3 व्यक्ति शैली। संभव के रूप में निहित आत्म के रूप में प्रत्येक टिप्पणी रखने की कोशिश:
मैं अक्सर डॉक्टर शैली बात करने के लिए करते हैं:
// Now we take $x and check whether it's valid for this pass
एक उपयोगी टिप। उदाहरण के लिए, इस फार्म:
// First, mumble the frabbitz.
blah blah
// Second, foobar the quux
blah blah
यह एक अच्छा कथा है, लेकिन यह कठिन कोड को संपादित करने में आता है, क्योंकि "सबसे पहले" और "दूसरा" भागों गलत हो सकता है। अंत में, वे टिप्पणियों में इतना अधिक नहीं जोड़ते हैं, लेकिन उन्हें एक नाजुक तरीके से पारस्परिक बनाते हैं।
मैं कभी कभी यह बहुत से लोगों को कोड संपादन कर रहे हैं कि कैसे पर और क्या प्रयोजन के लिए निर्भर हो सकता है, 1 व्यक्ति में बात इस
/*
Usage:
set_position(0.5, 0.5); // im in the center
set_position(0.0, 1.0); // im in the lower,left corner
*/
की तरह। अपने कोड में (जो सार्वजनिक दृश्य के लिए भी है) मैं शायद 'मैं' का उपयोग करके कुछ व्यक्तिगत टिप्पणियां जोड़ने में स्वतंत्र महसूस कर सकता हूं। एक सांप्रदायिक परियोजना में टिप्पणियों को एक सांप्रदायिक शैली का लक्ष्य रखना चाहिए और 'मैं' जगह से बाहर हो सकता है।
ध्यान दें कि टिप्पणियां नाजुक हैं और कई आधुनिक प्राधिकरण (जैसे स्वच्छ कोड) सुझाव देते हैं कि कार्यों और क्षेत्रों को सार्थक नाम लेना चाहिए। लेकिन, ज़ाहिर है, ऐसे कई स्थान हैं जहां व्याख्यात्मक टिप्पणियां अभी भी महत्वपूर्ण हैं।
मेरा विचार यह है कि आपको केवल उस शैली का उपयोग करना चाहिए जिसके साथ आप सबसे अधिक आरामदायक महसूस करते हैं।
एंबेडेड टिप्पणियां आपके कोड और आपके डेवलपर के कार्यान्वयन विवरण को समझने की कोशिश कर रहे अन्य डेवलपर्स द्वारा पढ़ी जाने वाली हैं। जब तक वे स्पष्ट और समझदार होते हैं, इससे कोई फर्क नहीं पड़ता कि वे शैली थोड़ा असामान्य हैं, व्याकरण थोड़ा खराब है, या कुछ वर्तनी त्रुटियां हैं। जो लोग इसे पढ़ रहे हैं उन्हें ऐसी चीजों की देखभाल करने से परे होना चाहिए।
एपीआई दस्तावेज बनाने के लिए निकाले गए टिप्पणियां शैली, व्याकरण और वर्तनी की नस्लों पर थोड़ा अधिक ध्यान देने योग्य हैं। लेकिन यहाँ भी सटीकता और पूर्णता कहीं अधिक महत्वपूर्ण हैं।
मुझे टिप्पणियों के बारे में टिप्पणी से असहमत होना है। मेरे लिए, आसानी से पढ़ने वाली टिप्पणियां वे हैं जो अच्छी तरह से लिखी जाती हैं - जिसका अर्थ है अच्छा व्याकरण, अच्छी वर्तनी, और अच्छी विराम चिह्न। –
अरे, देखो, मुझे टिप्पणियों में खराब व्याकरण वर्तनी आदि देखने के लिए परेशान भी लगता है। लेकिन मैं शिकायत के बिना इसके साथ रखूंगा। बहुत कम डेवलपर्स स्पार्कलिंग गद्य बनाने में सक्षम हैं। और यहां तक कि यदि वे थे, तो उनकी टिप्पणियां चमकाने की तुलना में वे अपने उत्पाद के साथ और अधिक उत्पादक चीजें कर सकते थे। –