पायथन में कार्यों के बारे में टिप्पणी करने का उचित तरीका क्या है?

174

क्या पायथन में कार्यों की टिप्पणी करने का एक आम तौर पर स्वीकृत तरीका है? निम्नलिखित स्वीकार्य है?

#########################################################
# Create a new user
#########################################################
def add(self):

python

— फुसलाना
स्रोत

318

इसे करने का सही तरीका डॉकस्ट्रिंग प्रदान करना है। इस तरह, help(add)आपकी टिप्पणी को भी समाप्त कर देगा।

def add(self):
    """Create a new user.
    Line 2 of comment...
    And so on... 
    """

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

देखें: PEP 257

— चिन्मय कांची
स्रोत

10

ध्यान दें कि इसे ट्रिपल-उद्धृत नहीं करना है; कोई भी स्ट्रिंग शाब्दिक काम करेगा। लेकिन आप मल्टीलाइन स्ट्रिंग में अधिक जानकारी डाल सकते हैं।

— इग्नासियो वाज़क्वेज़-अब्राम्स

5

हालांकि अधिवेशन तय करता है कि इसे ट्रिपल-उद्धृत किया जाना चाहिए। मैंने ऐसा डॉकस्ट्रिंग कभी नहीं देखा है जो नहीं था।

— चिन्मय कांची

2

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

— jcdyer

7

डॉकस्ट्रिंग को खोलने और बंद करने के लिए आप तीन सिंगल-कोट्स (तीन डबल-कोट्स के बजाय) का उपयोग कर सकते हैं।

— क्रेग मैकक्वीन

क्या आपको टिप्पणी भी नहीं करनी चाहिए?

— जौक्टी

25

एक डॉकस्ट्रिंग का उपयोग करें, जैसा कि अन्य पहले ही लिख चुके हैं।

आप एक कदम आगे भी जा सकते हैं और अपने डॉकस्ट्रिंग में एक सिद्धांत जोड़ सकते हैं, जिससे आपके कार्यों का स्वचालित परीक्षण हो जाएगा।

— टिम पीटरज़कर
स्रोत

3

लिंक किए गए पृष्ठ के माध्यम से अनुसरण किए बिना यह उत्तर काफी कमजोर है।

— xaxxon

18

डॉकस्ट्रिंग का उपयोग करें :

एक स्ट्रिंग शाब्दिक जो एक मॉड्यूल, फ़ंक्शन, क्लास या विधि परिभाषा में पहले कथन के रूप में होता है। ऐसा डॉकस्ट्रिंग __doc__उस वस्तु का विशेष गुण बन जाता है ।

सभी मॉड्यूलों में सामान्य रूप से डॉकस्ट्रिंग्स होने चाहिए, और एक मॉड्यूल द्वारा निर्यात किए जाने वाले सभी कार्यों और वर्गों में भी डॉक्ट्रिंग होनी चाहिए। सार्वजनिक विधियों ( __init__निर्माणकर्ता सहित ) में डॉकस्ट्रिंग्स भी होनी चाहिए। मॉड्यूल के डॉकस्ट्रिंग में एक पैकेज को प्रलेखित किया जा सकता है__init__.pyपैकेज निर्देशिका में फ़ाइल ।

पायथन कोड में कहीं और होने वाले स्ट्रिंग शाब्दिक भी प्रलेखन के रूप में कार्य कर सकते हैं। वे पायथन बाइटकोड कंपाइलर द्वारा पहचाने नहीं जाते हैं और रनटाइम ऑब्जेक्ट एट्रिब्यूट्स के रूप में पहुंच योग्य नहीं होते हैं (यानी असाइन नहीं किए जाते हैं __doc__), लेकिन दो प्रकार के अतिरिक्त डॉकस्ट्रिंग को सॉफ्टवेयर टूल्स द्वारा निकाला जा सकता है:

एक मॉड्यूल, वर्ग, या __init__विधि के शीर्ष स्तर पर एक साधारण असाइनमेंट के तुरंत बाद होने वाले स्ट्रिंग शाब्दिक "विशेषता डॉकिंग" कहा जाता है।

एक और डॉकस्ट्रिंग के तुरंत बाद होने वाले स्ट्रिंग शाब्दिक को "अतिरिक्त डॉक्ट्रिंग" कहा जाता है।

कृपया PEP 258 , "डॉकुटिल्स डिज़ाइन स्पेसिफिकेशन" [2] देखें , विस्तृत विवरण के लिए विशेषता और अतिरिक्त डॉकस्ट्रि ...

— डेनिज डोगन
स्रोत

10

अच्छी टिप्पणी के सिद्धांत काफी व्यक्तिपरक हैं, लेकिन यहां कुछ दिशानिर्देश दिए गए हैं:

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

— Dancrumb
स्रोत

7

इस बारे में कुछ भी व्यक्तिपरक नहीं है, डॉकिंग टिप्पणी का उपयोग करने के बारे में पायथन बहुत स्पष्ट है।

@ फजी लॉलीपॉप, मैं टिप्पणी की सराहना करता हूं, लेकिन आप ध्यान देंगे कि मेरा अंतिम बिंदु उस सटीक बिंदु को बनाता है। शायद ओपी का सवाल केवल पायथन में टिप्पणी करने के यांत्रिकी के बारे में है, लेकिन मुझे नहीं लगता कि मेरे जवाब में मतदान के नीचे वारंट है

— Dancrumb

7

अपने पायथन कोड में डॉकस्ट्रिंग्स का उपयोग करने के बारे में पढ़ें ।

पायथन डॉकस्ट्रिंग सम्मेलनों के अनुसार :

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

कोई सुनहरा नियम नहीं होगा, बल्कि यह टिप्पणी दें कि आपकी टीम के अन्य डेवलपर्स के लिए कुछ का मतलब है (यदि आपके पास एक है) या खुद के लिए भी जब आप सड़क पर छह महीने नीचे आते हैं।

— मैट नाड्रोफस्की
स्रोत

5

मैं एक दस्तावेज़ीकरण अभ्यास के लिए जाऊंगा जो एक दस्तावेज़ीकरण उपकरण जैसे स्फिंक्स के साथ एकीकृत होता है ।

पहला कदम एक का उपयोग करने के लिए है docstring:

def add(self):
 """ Method which adds stuff
 """

— jldupont
स्रोत

2

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

— PaulMcG
स्रोत

2

Docstrings का प्रयोग करें ।

यह फ़ंक्शन वर्णन टिप्पणियों के लिए PyCharm में निर्मित सुझाया गया सम्मेलन है :

def test_function(p1, p2, p3):
    """
    my function does blah blah blah

    :param p1: 
    :param p2: 
    :param p3: 
    :return: 
    """

— श्वेताभ शेखर
स्रोत

कि (के साथ लाइन के बाद def) इंडेंट नहीं होना चाहिए ? (कोई लफ्फाजी वाला सवाल नहीं।)

— पीटर मोर्टेंसन

0

जबकि मैं मानता हूं कि यह एक टिप्पणी नहीं होनी चाहिए, लेकिन सबसे (सभी?) जवाबों के रूप में एक डॉकस्ट्रिंग है , मैं numpydoc (एक डॉकस्ट्रिंग स्टाइल गाइड) जोड़ना चाहता हूं ।

यदि आप इसे इस तरह करते हैं, तो आप (1) स्वचालित रूप से प्रलेखन उत्पन्न कर सकते हैं और (2) लोग इसे पहचानते हैं और आपके कोड को पढ़ने का एक आसान समय होता है।

— मार्टिन थोमा
स्रोत

0

आप इसे करने के लिए तीन उद्धरणों का उपयोग कर सकते हैं।

आप एकल उद्धरण का उपयोग कर सकते हैं:

def myfunction(para1,para2):
  '''
  The stuff inside the function
  '''

या दोहरे उद्धरण:

def myfunction(para1,para2):
  """
  The stuff inside the function
  """

— aaron34weston
स्रोत