26

मैं आपसे अपने कोड में टिप्पणी लिखने की कोई सलाह और अनुभव सुनना चाहता हूं। आप उन्हें सबसे आसान और सूचनात्मक तरीके से कैसे लिखते हैं? कोड के कुछ हिस्सों पर टिप्पणी करते समय आपकी क्या आदतें हैं? शायद कुछ विदेशी सिफारिशें?

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

ठीक है, मैं शुरू कर दूंगा।

आमतौर पर, /* */जब मुझे कई लाइनों पर टिप्पणी करने की आवश्यकता होती है, तब भी मैं टिप्पणियों का उपयोग नहीं करता हूं।

लाभ : जब आप एक-पंक्ति टिप्पणियों के साथ इस तरह के वाक्यविन्यास को मिलाते हैं तो कोड नेत्रहीन बेहतर दिखता है। अधिकांश IDE में चयनित पाठ पर टिप्पणी करने की क्षमता होती है और वे आमतौर पर एक-पंक्ति वाक्य रचना के साथ करते हैं।

नुकसान : आईडीई के बिना ऐसे कोड को संपादित करना मुश्किल है।
किसी भी समाप्त टिप्पणी के अंत में "डॉट" रखें।

उदाहरण के लिए:
```
//Recognize wallpaper style. Here I wanted to add additional details
int style = int.Parse(styleValue);
//Apply style to image.
Apply(style);
```
लाभ : "डॉट" को केवल उन टिप्पणियों में रखें जिन्हें आपने समाप्त किया था। कभी-कभी आप अस्थायी जानकारी लिख सकते हैं, इसलिए "डॉट" की कमी आपको बताएगी कि आप वापस आना चाहते थे और इस टिप्पणी में कुछ अतिरिक्त पाठ जोड़ना चाहते थे।
पैरामीटर्स, कॉमेंटिंग पैरामीटर आदि में टेक्स्ट को संरेखित करें।

उदाहरण के लिए:
```
public enum WallpaperStyle
{
    Fill = 100,     //WallpaperStyle = "10"; TileWallpaper = "0".
    SizeToFit = 60, //WallpaperStyle = "6";  TileWallpaper = "0".
    Stretch = 20,   //WallpaperStyle = "2";  TileWallpaper = "0".
    Tile = 1,       //WallpaperStyle = "0";  TileWallpaper = "1".
    Center = 0      //WallpaperStyle = "0";  TileWallpaper = "0".
};
```
लाभ : आपको जो चाहिए वह ढूंढने के लिए बस बेहतर और नेत्रहीन आसान लगता है।

नुकसान : संरेखित करने और संपादित करने के लिए कठिन समय।
टिप्पणी में पाठ लिखें जिसे आप कोड का विश्लेषण करके प्राप्त नहीं कर सकते।

उदाहरण के लिए, बेवकूफ टिप्पणी:
```
//Apply style.
Apply(style);
```
लाभ : आपके पास टिप्पणियों में केवल उपयोगी जानकारी के साथ स्पष्ट और छोटा कोड होगा।

coding-style comments

— किरीलो एम
स्रोत

2

टिप्पणियों को विम में संरेखित करें: Align.vim का उपयोग करें और :3,7 Align //3-7 की तर्ज पर टिप्पणियों को संरेखित करें।

— बेनोइट

3

"आईडीई के बिना संपादित करना मुश्किल है" - ठीक है, क्या आप अक्सर ऐसा करते हैं?

3

मुझे लगता है कि प्रश्न में एक भाषा / पर्यावरण वरीयता को नोट किया जाना चाहिए। कुछ मौजूदा दिशानिर्देश हैं (.NET में मानक मानक xml टिप्पणियाँ हैं: msdn.microsoft.com/en-us/library/b2s063f7.aspx )।

— स्टीवन एवर्स

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

— उपयोगकर्ता अज्ञात

यह भी देखें: "टिप्पणियाँ एक कोड गंध हैं"

— gnat

16

नीचे दिए गए कुछ कथन काफी व्यक्तिगत हैं, हालांकि कुछ औचित्य के साथ, और इस तरह से हैं।

टिप्पणी प्रकार

संक्षिप्त संस्करण के लिए ... मैं इसके लिए टिप्पणियों का उपयोग करता हूं:

डेटा संरचनाओं में फ़ील्ड्स की व्याख्या करने वाली टिप्पणियां (उन लोगों के अलावा, मैं वास्तव में सिंगल लाइन टिप्पणियों का उपयोग नहीं करता हूं)
ब्लॉकों के ऊपर असाधारण या उद्देश्य-उन्मुख बहु-पंक्ति टिप्पणियां
सार्वजनिक उपयोगकर्ता और / या डेवलपर प्रलेखन स्रोत से उत्पन्न

विवरण और (संभवतः अस्पष्ट) कारणों के लिए नीचे पढ़ें।

अनुगामी टिप्पणियां

भाषा पर निर्भर करता है, या तो एकल-पंक्ति टिप्पणियों या बहु-पंक्ति टिप्पणियों का उपयोग कर रहा है। यह निर्भर क्यों करता है? यह सिर्फ एक मानकीकरण मुद्दा है। जब मैं C कोड लिखता हूं, मैं डिफ़ॉल्ट रूप से पुराने जमाने के ANSI C89 कोड का पक्ष लेता हूं, इसलिए मैं हमेशा पसंद करता हूं /* comments */।

इसलिए मैं सी के अधिकांश समय में ऐसा करूंगा, और कभी-कभी सी-जैसे सिंटैक्स वाली भाषाओं के लिए (कोडबेस की शैली पर निर्भर करता है):

typedef struct STRUCT_NAME {
  int fieldA;                /* aligned trailing comment */
  int fieldBWithLongerName;  /* aligned trailing comment */
} TYPE_NAME;

Emacs अच्छा है और मेरे साथ ऐसा करता है M-;।

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

मल्टी-लाइन टिप्पणियाँ

इसके लिए सिंगल-लाइन टिप्पणियों का उपयोग करते हुए मैं आपके संकल्पना से असहमत हूं। मैं इसका उपयोग करता हूं:

/*
 * this is a multi-line comment, which needs to be used
 * for explanations, and preferably be OUTSIDE the a
 * function's or class' and provide information to developers
 * that would not belong to a generated API documentation.
 */

या यह (लेकिन मैं ऐसा अक्सर नहीं करता हूं, एक व्यक्तिगत कोडबेस को छोड़कर या अधिकतर कॉपीराइट नोटिस के लिए - यह मेरे लिए ऐतिहासिक है और मेरी शैक्षिक पृष्ठभूमि से आता है। दुर्भाग्य से, अधिकांश आईडीई ऑटो-प्रारूप का उपयोग करते समय इसे खराब कर देते हैं) ।

/*
** this is another multi-line comment, which needs to be used
** for explanations, and preferably be OUTSIDE the a
** function's or class' and provide information to developers
** that would not belong to a generated API documentation.
*/

यदि वास्तव में जरूरत है, तो मैं इनलाइन का उपयोग कर टिप्पणी करूंगा, जो मैंने पहले टिप्पणी के लिए उल्लेख किया था, अगर यह एक अनुगामी स्थिति में इसका उपयोग करने के लिए समझ में आता है। उदाहरण के लिए, या switch's caseस्टेटमेंट्स (दुर्लभ, मैं अक्सर स्विच का उपयोग नहीं करता)' या जब मैं किसी if ... elseनियंत्रण प्रवाह में शाखाओं का दस्तावेजीकरण करता हूं, तो एक बहुत ही विशेष रिटर्न केस पर । यदि यह इनमें से एक नहीं है, तो आम तौर पर फ़ंक्शन / विधि / ब्लॉक के चरणों की रूपरेखा के दायरे के बाहर एक टिप्पणी ब्लॉक मेरे लिए अधिक समझ में आता है।

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

try {
  /* you'd have real code here, not this comment */
} catch (AwaitedException e) {
  /*
   * Nothing to do here. We default to a previously set value.
   */
}

जो मेरे लिए पहले से ही बदसूरत है लेकिन मैं कुछ परिस्थितियों में सहन करूंगा।

प्रलेखन टिप्पणियाँ

जावदोक और अल।

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

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

टिप्पणी-बाहर कोड

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

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

टिप्पणियाँ शैलियाँ

मैं आमतौर पर लिखता हूं:

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

साहित्य प्रोग्रामिंग पर एक नोट

हो सकता है कि आप लिटरेट प्रोग्रामिंग में दिलचस्पी लेना चाहें , जैसा कि डोनाल्ड नुथ ने इस पत्र में प्रस्तुत किया है ।

साक्षर प्रोग्रामिंग प्रतिमान, [...] कंप्यूटर द्वारा लगाए गए तरीके और क्रम में प्रोग्राम लिखने से एक कदम दूर का प्रतिनिधित्व करता है, और इसके बजाय प्रोग्रामर को अपने विचारों के तर्क और प्रवाह द्वारा मांग किए गए क्रम में प्रोग्राम विकसित करने में सक्षम बनाता है। 2 साहित्य कार्यक्रम एक साधारण मानव भाषा में तर्क के निर्बाध विस्तार के रूप में लिखे जाते हैं, बहुत कुछ एक निबंध के पाठ की तरह [...]।

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

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

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

— haylem
स्रोत

प्रलेखन टिप्पणियों से टिप्पणी-आउट कोड को अलग करने के लिए +1। मैं उन शिकार से नफरत करता हूं: पी

— डेल्ट्रीम

@ डैल्ट्रीम: धन्यवाद मुझे आपका दर्द महसूस हो रहा है, मैं अपने वर्तमान उत्पाद में खुद भी उन लोगों का एक झुंड शिकार कर रहा हूं। एस सी एम एस के लिए एक कारण के लिए मौजूद हैं ... मैं बहुत बस ग्रहण या Emacs में एक regex के साथ एक पूर्ण-पाठ खोज का उपयोग करने के लिए और सिर्फ उन्हें एक के बाद एक उन्मूलन परीक्षा कर रहा हूँ ... मैं और अधिक उत्पादक काम करने के लिए, उदासी है :(

— 0

कृपया टिप्पणियों में कार्रवाई या कार्य टैग के उपयोग पर यह उत्तर भी देखें ।

— १३:३६ बजे ज्वलंत नवरात्रि

14

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

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

public void Login(string username, string password)
{
    // Get the user entity
    var user = userRepository.GetUser(username);


    // Check that the user exists
    if (user == null)
    {
        throw new UserNotFoundException();
    }

    // Check that the users password matched
    if (user.HashedPassword != GetPasswordHash(password))
    {
        throw new InvalidUsernamePasswordException();
    }

    //Check that the users account has not expired
    if (user.Expired)
    {
        throw new UserExpiredException();
    }

    //Mark user as logged in
    ...
}

यह उस चीज़ के लिए फिर से लिखा जा सकता है जो कहीं अधिक पठनीय है और शायद पुन: प्रयोज्य है:

public void Login(string username, string password)
{
    var user = GetUserForUsername(username);

    CheckUsersPasswordMatched(user, password);

    CheckUserAccountNotExpired(user);

    MarkUserAsLoggedIn(user);
}

private void User GetUserForUsername(string username)
{
    var user = userRepository.GetUser(username);

    if (user == null)
    {
        throw new UserNotFoundException();
    }
    return user;
}

private void CheckUsersPasswordMatched(User user, string password)
{
    if (user.HashedPassword != GetPasswordHash(password))
    {
        throw new InvalidUsernamePasswordException();
    }
}

private void CheckUserAccountNotExpired(User user)
{
    if (user.Expired)
    {
        throw new UserExpiredException();
    }
}

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

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

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

— Bronumski
स्रोत

2

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

— केविन

2

यह वही है जो मैं यहाँ कहने आया था। वास्तव में, मैं केवल चर नाम, विधि के नाम, वर्ग के नाम, आदि के बारे में सोचने के रूप में ज्यादा खर्च करता हूं, जैसा कि मैं कोड लिख रहा हूं। मेरा मानना है कि परिणाम, बहुत सहायक कोड है। निश्चित रूप से, मेरे पास कभी-कभी ऐसे तरीके होते हैं जिन्हें कुछ नाम दिए जाते हैं जैसे checkIfUnitInvestigationExistsAndCreateNewRootCauseListIfItDoes () ... हाँ, विधि के नाम SOMETIMES लंबे समय तक मिलते हैं, लेकिन मुझे लगता है कि कोड की suportability विकास का सबसे महत्वपूर्ण पहलू है (रिलीज की गति से हटकर)।

— jeremy.mooer

5

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

//Apply style.

Apply(style);

होना चाहिए

// Unlike the others, this image needs to be drawn in the user-requested style apply(style);

हममें से अधिकांश मौजूदा कोड पर टीमों में काम करते हैं, बाकी टीम जिस तरह से करती है, उसे उसी तरह से प्रारूपित करती है, जिस तरह से यह पहले से ही किया जा रहा है। सुंदर से कहीं अधिक महत्वपूर्ण की संगति।

— mattnz
स्रोत

अधिक ध्यान से पढ़ें कि इसके लिए क्या उदाहरण है। मैंने पहले ही उल्लेख किया है कि: "उदाहरण के लिए, बेवकूफ टिप्पणी:"।

— Kyrylo M

1

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

— मटनज

3

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

— डेव
स्रोत

2

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

— किरीलो एम
स्रोत

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

— एडम बायरटेक

2

मैं अक्सर उस तरह की टिप्पणियों को देखता हूं, और कुछ उपकरण स्वचालित रूप से इसे इस तरह से उत्पन्न करते हैं:

/** 
 * This is an example, how to waste vertical space,
 * and how to use useless asterixes.
 */

दो लाइनें कम:

/** This is an example, how to spare vertical space,
    and how to avoid useless asterixes. */

आईडीई और संपादक, नोटपैड-स्तर से थोड़ा ऊपर, टिप्पणियों का पता लगाने और उन्हें एक अलग रंग में मुद्रित करने में सक्षम हैं। लाइन की शुरुआत को तारांकन के साथ सजाने की कोई आवश्यकता नहीं है।

आप कुछ बाइट्स भी छोड़ देते हैं, अगर आप इंडेंटेशन के लिए टैब का उपयोग करते हैं।

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

— अज्ञात उपयोगकर्ता
स्रोत

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

— 11'13

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

— 11'11

मुझे अपना समय तह करना और कोड खोदना पसंद नहीं है। मैं आपके कमोडोर-तर्क से सहमत होता, अगर बाइट्स का एक ही फायदा होता, लेकिन वे नहीं करते। यदि आपके संपादक में कोड-हाइलाइटिंग नहीं है, तो जाओ, अपने आप को एक कमोडोर64 खरीदो। :) इंडेंटेशन तर्क धारण नहीं करता है, क्योंकि यदि इंडेंटेशन टिप्पणी को कोड से अलग करता है, तो यह कोड को टिप्पणी से भी अलग करता है। टिप्पणी कोड का एक बड़ा टुकड़ा देखें - एक तारांकन का एक ब्लॉक एक जोर के रूप में काम करता है।

— उपयोगकर्ता अज्ञात

जैसा मैंने कहा, व्यक्तिगत हो सकता है। लेकिन इसके बारे में सोचो: क्या आप वास्तव में वेब ब्राउज़ करते समय उन सभी चमकदार और फंकी विज्ञापनों को देखते हैं? ज्यादातर लोग नहीं करते हैं। आप बस उन्हें ब्लॉक करना सीखते हैं, जैसा कि आपने उन्हें एक सामान्य पैटर्न के रूप में पंजीकृत किया है जिसे आप आसानी से माइंड-ब्लॉक कर सकते हैं। डॉक्स टिप्पणियों के लिए मेरे लिए काम करता है। तह के बारे में, यह थकाऊ हो सकता है। जावा के लिए, मेरा ग्रहण डिफ़ॉल्ट रूप से बहुत सी चीजों को मोड़ने के लिए सेट है, क्योंकि मैं अपनी जावा फाइलें खोलना पसंद करता हूं और उन्हें सी हेडर फाइलों (डब्ल्यू / ओ की रूपरेखा दृश्य का उपयोग करके) की तरह सर्वेक्षण करने में सक्षम हूं। और मैं माइलिन का उपयोग केवल उन बिट्स को प्रदर्शित करने के लिए करता हूं जिन पर मैं काम करता हूं।

— प्रातः

हाँ, मैंने उन्हें अवरुद्ध करना सीखा - एक प्लगइन के साथ, जिसे विज्ञापन अवरोधक कहा जाता है। ग्रहण का एक गुना कार्य है, लेकिन gedit, जिसका उपयोग मैं छोटे, एकल फ़ाइल कार्यक्रमों के लिए करता हूं, नहीं है।

— उपयोगकर्ता अज्ञात

2

यहाँ एक "एंटी-पैटर्न" है जो मैंने अपनी नौकरी के कोड में पाया है: "परिवर्तन लॉग" के रूप में टिप्पणियों का उपयोग; यह वही है जो आपके संस्करण नियंत्रण प्रणाली में लॉग के लिए है। कोड चीजों से अटे पड़े हैं:

// 05-24-2011 (John Doe): Changed this method to use Foo class instead of Bar

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

// (John Doe) 05-24-2011 not sure why we are using this object?
FooBar oFooBar = Quux.GetFooBar(iFooBarID, bSomeBool);
oFooBar.DiscombobulateBaz();

// (John Doe). This method is poorly named, it's used for more 
// than just frazzling arvadents
public int FrazzleArvadent(int iArvadentID)

— वेन मोलिना
स्रोत

2

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

— किरीलो एम
स्रोत

1

कोड रीडर आमतौर पर तीन सवालों के जवाब देने की कोशिश कर रहे हैं:

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

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

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

— केविन क्लाइन
स्रोत

शैली और टिप्पणी कोड की सिफारिशें

टिप्पणी प्रकार

अनुगामी टिप्पणियां

मल्टी-लाइन टिप्पणियाँ

प्रलेखन टिप्पणियाँ

टिप्पणी-बाहर कोड

टिप्पणियाँ शैलियाँ

साहित्य प्रोग्रामिंग पर एक नोट