टिप्पणी / इन-कोड प्रलेखन शैलियाँ

Question

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

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

double MyFunction(const int MyParam);
// Function: MyFunction
// Summary: Does stuff with MyParam.
// Input: int MyParam - The number to do stuff with.
// Output: MyParam with stuff done to it.

इन-कोड प्रलेखन लिखते समय, आप कितने विस्तृत हैं?

Comments

आपका उदाहरण सरल है। व्यवहार में, आप पैरामीटर के प्रकार की तुलना में कहीं अधिक बाधाओं को निर्दिष्ट करेंगे, यदि यह एक इंट है, तो यह एक पूर्णांक होना चाहिए जो मान X और Y है। यदि रिटर्न मान दोगुना है, तो आप यह निर्दिष्ट कर सकते हैं कि यह कितना सटीक है , और यह कैसे मान हो सकता है (एक फ़ंक्शन मौजूद हो सकता है जो ठीक 1.01, 2.31 और 5.01!) लौटाता है। अधिक विशिष्ट बनें और आप अधिक पुनरावृत्ति नहीं देखेंगे ...

— पुराना खाता

Answer 1

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

कोड में अच्छी टिप्पणियां दोहराई नहीं जातीं। वे सवाल का जवाब "क्यों?" इसके बजाय "क्या?" या कैसे?" वे इनपुट के बारे में उम्मीदों को कवर करते हैं, साथ ही साथ कुछ शर्तों के तहत कोड कैसे व्यवहार करेंगे। वे कवर करते हैं कि एल्गोरिथ्म वाई के बजाय एल्गोरिदम एक्स को क्यों चुना गया। संक्षेप में, बिल्कुल चीजें जो कोड पढ़ने से किसी और ^{1 के} लिए स्पष्ट नहीं होंगी ।

---

^{1: कोई और व्यक्ति जो उस भाषा से परिचित है जिसे कोड में लिखा गया है। सिखाने के लिए टिप्पणी न लिखें, जानकारी को पूरक करने के लिए टिप्पणी करें।}

Comments

+1, हालांकि यह सुनिश्चित करें कि आपको याद है कि आपके लिए जो स्पष्ट है वह दूसरे प्रोग्रामर के लिए स्पष्ट नहीं हो सकता है।

— जोश के

@ जोश: अच्छी बात है, इसलिए मैंने जवाब संपादित किया।

— लैरी कोलमैन

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

— जॉरिस मेस

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

— लैरी कोलमैन

@ लॉरी: मैंने इसे टिप्पणी में पढ़ा है कि घोषणाओं और कोड के माध्यम से हर बार जब मैं किसी फ़ंक्शन का पुन: उपयोग करना चाहता हूं। अंदाज की बात है कि मैं एक आलसी आदमी हूं।

— जोरिस मेय्स

Answer 2

कई भाषाओं में एपीआई दस्तावेज़ पीढ़ी की विशेषताएं हैं जैसे रूबी, जावा, सी # और सी ++ (कमांड लाइन टूल के माध्यम से)। जब आप इसके बारे में इस तरह से सोचते हैं, तो यह एपीआई डॉक्स को बहुत अधिक महत्वपूर्ण बनाता है। आखिरकार, यह सवाल का जवाब देता है "मैं कैसे करूँ ...?" इसलिए मैं कुछ भी दोहराव नहीं करूंगा जैसे Function: MyFunctionकि फ़ंक्शन का नाम सभी के लिए देखने के लिए सरल है। एपीआई डॉक्स जेनरेशन टूल्स मेरे लिए काफी स्मार्ट हैं। हालाँकि, निम्नलिखित विवरण उपयोगी हैं, विशेष रूप से सार्वजनिक विधियों / कार्यों पर:

• सारांश (यह क्या करता है और जब इसका उपयोग कैसे करना है इसका एक सारांश)
• मापदंडों की सूची और क्या अपेक्षित है
• रिटर्न वैल्यू (आउटपुट) क्या होगा
• कोई भी अपवाद जो स्पष्ट रूप से और क्यों फेंका जा सकता है

जब आप कोड डीबग करने का प्रयास कर रहे हैं तो ये उपयोगी संदर्भ उपकरण बन सकते हैं। कई IDE अपने टूल युक्तियों में API डॉक्स का भी उपयोग करेंगे क्योंकि आप फ़ंक्शन के नाम पर होवर करते हैं।

यदि यह उन विशेषताओं के बिना एक भाषा है, तो टिप्पणियां मदद करती हैं, लेकिन लगभग उतना नहीं।

Comments

यदि आउटपुट विवरण सारांश के साथ शामिल है तो क्या यह स्वीकार्य है? उदाहरण के लिए, Returns the square root of Xयह भी बताता है कि रिटर्न वैल्यू क्या है।

— Maxpm

हाँ; छात्रों को जो सिखाया जाना चाहिए, वह इन प्रलेखन सुविधाओं का उपयोग करना है।

— जेरेमी

अगर संभव हो तो मैं एपीआई डॉक्स को तार्किक अमूर्तता पर रखना पसंद करता हूं। उदाहरण के लिए, Returns the color for this rayया Returns the requested Message, or null if it can't be found। लेकिन हां, सारांश एपीआई डॉक्स का मांस है।

— बेरिन लोरिट्स्क

Answer 3

यदि यह एक सार्वजनिक एपीआई विधि है तो हाँ आपको विस्तृत प्रलेखन प्रदान करना चाहिए, विशेष रूप से मापदंडों और अपेक्षित व्यवहार पर। कई लोगों को लगता है कि यह निजी तरीकों / कार्यों, YMMV के लिए आराम दिया जा सकता है।

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

अब से 3 महीने पहले सुबह 3 बजे पहनने के लिए अपने स्वयं के थोड़े से बुरे समय के बारे में सोचें। आप अपने आप को अपने भयानक सार्वजनिक डॉक्स के लिए धन्यवाद दे रहे होंगे जो यह पता लगाने का विरोध कर रहे थे कि पैरामीटर (बुलियन फ्लैग) का क्या मतलब है ...

Comments

कभी-कभी फ़ंक्शंस में कोने-केस व्यवहार हो सकता है जो कि एल्गोरिथ्म का मतलब होता है। उदाहरण के लिए, floatपूर्णांक को ०.५ जोड़कर और परिणाम के तल पर ले जाने के कारण ०.५ से float नीचे सबसे बड़ी गलती से गोल किया जा सकता है। ऐसे मामलों में, कभी-कभी यह अंतर करना महत्वपूर्ण हो सकता है कि क्या किसी फ़ंक्शन को निकटतम पूर्णांक (या अगले उच्च पूर्णांक जब दो संभावित मान समतुल्य होते हैं) के रूप में परिभाषित किया जाना चाहिए, या 0.5 जोड़कर (संभवतः एक मध्यवर्ती दौर चरण के साथ और) परिणाम की मंजिल ले रहा है।

— सुपरकैट

Answer 4

यह समान है कि अधिकांश-डॉक फ्रेमवर्क कोड-इन प्रलेखन (JavaDoc, PHPDoc, आदि) को कैसे पार्स करते हैं।

जावा से, IDE द्वारा स्वतः-जनरेट किया गया:

/**
 * [Description]
 * @param str [Description]
 * @param isCondition [Description]
 * @return [Description]
 */
public int testFunction(String str, boolean isCondition) {
    ...
}

यह वही प्रारूप है जिसका उपयोग अंतर्निहित भाषा सुविधाओं के लिए प्रलेखन उत्पन्न करने के लिए किया जाता है - उदाहरण: http://download.oracle.com/javase/6/docs/api/java/lang/String.html

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

एकमात्र बिट मुझे अक्सर कुछ हद तक बेमानी लगता है, यह विवरण है - आमतौर पर यह मेरे तरीके के विवरण के समान है।

Answer 5

टिप्पणियाँ के लिए दो उद्देश्य हैं:

1. वे आपको यह याद दिलाने के लिए काम करते हैं कि आपका कोड क्या करता है जब आप महीनों / वर्षों बाद वापस आते हैं। इस तरह से आपको अपनी मेमोरी को रीफ्रेश करने के लिए अपने कोड को फिर से पढ़ने और विश्लेषण करने की आवश्यकता नहीं है।
2. वे अन्य लोगों से संबंधित हैं जो आपके कोड के साथ पढ़ रहे हैं या काम कर रहे हैं जो आपका कोड कर रहा है।

बेशक इस दृष्टिकोण के लिए कई अलग-अलग तरीके हैं, लेकिन अधिक गहन और सुसंगत आप बेहतर हैं। प्रभावी टिप्पणी सीखने में समय लगता है जैसे प्रभावी प्रोग्रामिंग करता है। ध्यान रखें कि स्कूल में टिप्पणियों के बिंदु को देखने के लिए कठिन है क्योंकि आप जिस पर काम कर रहे हैं वह कभी भी वास्तव में वारंट के लिए पर्याप्त नहीं है, लेकिन वे सिर्फ आपको इसे पेश करने की कोशिश कर रहे हैं। और आमतौर पर जिस तरह से आप इसे करने के लिए सिखाते हैं वह आपके प्रोफेसर की शैली है किसी भी तरह से मानक नहीं है। जो आपके लिए काम करता है उसे विकसित करें। और याद रखना ... बेवकूफी भरी टिप्पणी जैसी कोई बात होती है! :) उदाहरण:

a += 1; //adds 1 to the value in a

वास्तव में? धन्यवाद! जबरदस्त हंसी

Answer 6

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

/*
* Finds all the locations where you have access to for this client and returns them in an array .
* @author Radu
* @version 1.0
* @param int $id ( The id of the client for which you're requesting access. )
* @param object $db ( A resource of type Mysql, representing a connection to mysql database, if not supplied the function will connect itself. )
* @return array ( Returns array with id's of locations that you are allowed to see, an empty array if you do not have acces to any locations or returns FALSE and triggers a Warning if any error occuread )
* @use array allowed_locations ( $id [, $db] )
*/
function allowed_locations($id, $db=NULL){ ... }

और @Larry कोलमैन की तरह, इनलाइन टिप्पणियों ने बताया कि आपने कुछ कोड क्यों बनाए।

$funcResult = SomeFunction();
if(is_array($funcResult))
{    //Beacause SomeFunction() could return NULL, and count(NULL) = 1
    $c = count($funcResult);
} else {
    $c = 0;
}
if($c == 1)
{
 ... 
}else
{
 ...
}

Answer 7

अगर यह डॉक पीढ़ी की सेवा में है, तो मौखिक टिप्पणी (हालांकि चिड़चिड़ाहट) शायद एक अच्छी बात है। यद्यपि आपको टिप्पणियों के शीर्ष पर बने रहने और उन्हें अद्यतित रखने के लिए टीम लक्ष्य बनाना होगा।

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

मैं स्पष्ट रूप से संयुक्त राष्ट्र की टिप्पणी कोड स्पष्ट नहीं होगा । मुझे वर्णनात्मक अभिकथन या विधियों के साथ कुछ परीक्षण दें और मैं खुश और सूचित हूं।