Python प्रोग्रामिङको संसार

Python docstring पूर्ण गाइड: लेखन शैली र सर्वोत्तम अभ्यास

अपवाद ह्यान्डलिङ र त्रुटि नियन्त्रण
目次

1. Python को docstring के हो?

Python मा docstring भनेको, कार्य, वर्ग, मोड्युल आदि कोडमा व्याख्या थप्नको लागि विशेष स्ट्रिङ हो। docstring ले कोडको मर्मत सम्भार क्षमता बढाउँछ, अन्य विकासकर्ताहरूलाई कोड बुझ्न सजिलो बनाउँछ, र अत्यन्त महत्वपूर्ण भूमिका खेल्दछ। साथै, तल उल्लेख स्वचालित दस्तावेज निर्माण उपकरण（उदाहरण: Sphinx）प्रयोग गरेर, docstring लाई उपयोग गरेर दस्तावेज बनाउन सकिन्छ।

docstring को स्थान र स्वरूप

docstring लाई, लक्ष्य कार्य, वर्ग, मोड्युलको परिभाषा पछि राखिन्छ, र ट्रिपल डबल कोट्सले घेरिएको मूल स्वरूप हो। तलको जस्तै संरचना सामान्य छ।
def 関数名(引数):
    """
    यहाँ कार्यको छोटो विवरण लेख्नुहोस्।

    आर्गुमेन्ट:
        परिमाणको नाम (प्रकार): परिमाण सम्बन्धी विस्तृत विवरण
    रिटर्न मान:
        प्रकार: फिर्ती मान सम्बन्धी विवरण
    """
    pass
docstring लाई Python को बिल्ट‑इन फङ्क्शन help() वा सम्पादकभित्रको सहायक प्रदर्शनमा पनि प्रयोग गरिन्छ, र कोडको दस्तावेजको रूपमा ठूलो भूमिका खेल्दछ।

2. docstring को आधारभूत लेखन तरिका

Python को docstring प्रयोग गरिन्छ कार्यहरू वा वर्गहरूको विशिष्टता छोटो र स्पष्ट रूपमा वर्णन गर्न। स्वरूपको रूपमा, पहिलोमा कार्यको उद्देश्यलाई छोटकरीमा वर्णन गरिन्छ, त्यसपछि आर्ग्युमेन्टहरू, रिटर्न मानहरू, त्रुटिहरू आदि बारे लेखिन्छ। Python को आधिकारिक शैली मार्गदर्शक PEP 257 अनुसार, स्थिरता कायम रहन्छ, र अन्य विकासकर्ताहरूले पनि बुझ्न सजिलो कोड बनाइन्छ।

आधारभूत docstring को संरचना

एक पङ्क्तिको docstring अत्यन्त छोटो व्याख्या दिन प्रयोग गरिन्छ। सामान्यतया, कार्यको कार्यक्षमता एक शब्दमा वर्णन गर्न प्रयोग गरिन्छ, र तलको जस्तै लेखिन्छ।
def add(a, b):
    """दुई संख्याहरूलाई जोडेर परिणाम फिर्ता गर्दछ।"""
    return a + b
बहु-पङ्क्तिको docstring विस्तृत व्याख्या आवश्यक परे प्रयोग गरिन्छ। कार्यको व्यवहार, आर्ग्युमेन्टहरू, रिटर्न मानहरू बारे विशिष्ट रूपमा लेखिन्छ, र नयाँ पङ्क्तिहरू प्रयोग गरेर पढ्न सजिलो बनाइन्छ।
def add(a, b):
    """
    दुई संख्याहरूलाई जोडेर, त्यसको परिणाम फिर्ता गर्दछ।

    आर्ग्युमेन्टहरू:
        a (int): जोडिने पहिलो संख्या
        b (int): जोडिने दोस्रो संख्या

    रिटर्न मान:
        int: दुई संख्याहरूको योग
    """
    return a + b

3. docstring को शैली（Google शैली、NumPy शैली、reStructuredText शैली）

docstring को शैली प्रोजेक्ट र प्रयोग हुने उपकरण अनुसार विभिन्न रूपहरूमा उपलब्ध छ। मुख्यतया Google शैली, NumPy शैली, reStructuredText शैलीका तीनवटा व्यापक रूपमा प्रयोग हुन्छन्。

Google शैली

Google शैलीले संक्षिप्त र दृश्यात्मक रूपमा बुझ्न सजिलो वर्णनलाई विशेषता बनाउँछ। आर्ग्युमेन्टहरू र रिटर्न मानहरूArgs रReturns जस्ता सेक्शन शीर्षक अन्तर्गत लेखिन्छ, जसले Python फङ्सनको व्याख्या सहजै बुझ्न मद्दत गर्छ।
def add(a, b):
    """
    दुई संख्याहरूलाई जोडेर फिर्ता गर्छ।

    Args:
        a (int): जोडिने पहिलो संख्या
        b (int): जोडिने दोस्रो संख्या

    Returns:
        int: दुई संख्याहरूको योग
    """
    return a + b

NumPy शैली

NumPy शैलीले विस्तृत व्याख्या प्रदान गर्ने ढाँचा हो, विशेष गरी वैज्ञानिक गणना र डेटा विश्लेषणमा प्रयोग हुने लाइब्रेरीहरूको दस्तावेजमा व्यापक रूपमा अपनाइएको छ। Parameters रReturns जस्ता सेक्शन शीर्षकहरू प्रयोग गरी, आर्ग्युमेन्टहरू र रिटर्न मानहरूको विस्तृत विवरण लेखिन्छ।
def add(a, b):
    """
    दुई संख्याहरूलाई जोडेर फिर्ता गर्छ।

    Parameters
    ----------
    a : int
        जोडिने पहिलो संख्या
    b : int
        जोडिने दोस्रो संख्या

    Returns
    -------
    int
        दुई संख्याहरूको योग
    """
    return a + b

reStructuredText शैली

reStructuredText शैली Sphinx नामक दस्तावेज निर्माण उपकरणमा प्रयोग हुने ढाँचा हो, र जटिल प्रोजेक्टहरूमा प्रायः प्रयोग हुन्छ। Sphinx ले यो शैली प्रयोग गरी, कोडबाट स्वचालित रूपमा HTML वा PDF स्वरूपको दस्तावेज उत्पन्न गर्छ।
def add(a, b):
    """
    दुई संख्याहरूलाई जोड्छ।

    :param a: जोडिने पहिलो संख्या
    :type a: int
    :param b: जोडिने दोस्रो संख्या
    :type b: int
    :return: दुई संख्याहरूको योग
    :rtype: int
    """
    return a + b

4. PEP 257 र सर्वश्रेष्ठ अभ्यासहरू

Python को docstring सम्बन्धी आधिकारिक शैली मार्गदर्शिका PEP 257 मा, docstring लेख्ने तरिकाबारे स्पष्ट दिशानिर्देशहरू दिइएको छ। यसलाई पालना गर्दा, कोडको पढ्नयोग्यता सुधार हुन्छ, र अन्य विकासकर्ताहरू तथा आफैंले कोडलाई सजिलै बुझ्न सकिन्छ।

PEP 257 को महत्वपूर्ण बुँदाहरू

  1. एक पङ्क्तिको docstring साधारण फङ्सन वा मेथडहरूका लागि, एक पङ्क्तिमा संक्षिप्त व्याख्या लेख्न सिफारिस गरिन्छ।
  2. बहु-पङ्क्तिको docstring विस्तृत व्याख्या आवश्यक परेमा, बहु-पङ्क्तिको docstring प्रयोग गरिन्छ। यस अवस्थामा, पहिलो पङ्क्ति सानो सारांश हो, त्यसपछि खाली पङ्क्ति राखी विस्तृत व्याख्या लेखिन्छ।
  3. इन्डेन्ट र खाली पङ्क्तिको प्रयोग docstring भित्र, लाइनब्रेक र इन्डेन्ट प्रयोग गरेर पढ्नयोग्यता बढाइन्छ। साथै, फङ्सनका आर्गुमेन्ट र रिटर्न मानको जानकारीलाई स्पष्ट रूपमा विभाजन गरेर, पढ्न सजिलो बनाइन्छ।

सर्वश्रेष्ठ अभ्यासहरू

  • संक्षिप्त र स्पष्ट व्याख्या docstring संक्षिप्त भए पनि, फङ्सन वा क्लास के गर्छ भन्ने कुरा ठीकसँग बताउनुपर्छ। अनावश्यक जानकारी हटाउँदै, महत्वपूर्ण भागलाई विस्तृत रूपमा लेखौं।
  • एकरूप शैलीको कायम राख्नु पूरा प्रोजेक्टमा docstring को शैलीलाई एकरूप बनाउँदा, पढ्नयोग्यता सुधार हुन्छ। Google शैली, NumPy शैली जस्ता, टिम वा प्रोजेक्टको लागि उपयुक्त शैली चयन गरौं।

5. docstring प्रयोग गरेर परीक्षण（doctest）

Python मा, docstring भित्रको नमुना कोड वास्तवमा अपेक्षित अनुसार काम गर्छ कि गर्दैन भनेर परीक्षण गर्ने सुविधा को रूपमा doctest मोड्युल छ। यो सुविधालाई प्रयोग गरेर, docstring मा लेखिएको कोड उदाहरण सही छ कि छैन स्वचालित रूपमा जाँच गर्न सकिन्छ, जसले कोडको विश्वसनीयता बढाउँछ। est प्रयोग गर्दा, दस्तावेजीकृत कोडको परीक्षण सजिलै गर्न सम्भव हुन्छ।

doctest को आधारभूत प्रयोग

doctest ले docstring भित्रको नमुना कोडलाई स्वचालित रूपमा पत्ता लगाउँछ र त्यसको नतिजा लेखिएको अनुसारको आउटपुट हो कि होइन जाँच गर्छ। तल देखाइएझैँ, if __name__ == "__main__": ब्लकमा doctest थपेर परीक्षण चलाउन सकिन्छ।
def add(a, b):
    """
    दुई संख्याहरूलाई जोडेर फिर्ता गर्छ।

    Args:
        a (int): पहिलो संख्या
        b (int): दोस्रो संख्या

    Returns:
        int: दुई संख्याहरूको योग

    Example:
        >>> add(2, 3)
        5
        >>> add(0, 0)
        0
    """
    return a + b

if __name__ == "__main__":
    import doctest
    doctest.testmod()
उपरोक्त उदाहरणमा, doctest ले docstring भित्रको कोड नमुना चलाएर नतिजा तुलना गर्छ। परीक्षण सफल भएमा केही पनि देखाइँदैन, तर असफल भएमा त्रुटि सन्देश देखाइन्छ। यसले docstring भित्रको नमुना कोड सधैं सही छ भन्ने ग्यारेन्टी दिन्छ।

doctest प्रयोग गर्ने फाइदाहरू

  1. कोडको स्थिरता doctest प्रयोग गरेर, docstring भित्र लेखिएको नमुना कोड वास्तवमा चल्छ कि छैन जाँच गर्न सकिन्छ, जसले कोड र दस्तावेजको स्थिरता कायम राख्छ। यसले दस्तावेजलाई सधैं नवीनतम कोडसँग मिल्दो बनाउँछ।
  2. परीक्षणको स्वालन doctest सजिलै स्वचालित गर्न सकिन्छ, र फङ्क्शन वा क्लासको परीक्षण म्यानुअली गर्न आवश्यक छैन। केवल doctest चलाएमा, docstring भित्रका सबै कोड उदाहरणहरू परीक्षण हुन्छन्, जसले त्रुटिहरू घटाउँछ।

6. व्यावहारिक उदाहरण: docstring लाई प्रयोग गरेर कोडको दस्तावेजीकरण

वास्तवमाdocstringलाई प्रयोग गर्दा, Python कोडको पठनीयता धेरै सुधार हुन्छ, र अन्य विकासकर्ताहरूका लागि बुझ्न सजिलो हुन्छ। यहाँ, वर्ग र कार्यहरूमा उपयुक्तdocstringथपेर, Sphinx प्रयोग गरेर स्वचालित रूपमा दस्तावेजीकरण गर्ने प्रक्रिया प्रस्तुत गरिन्छ।

वर्गको लागि docstring लेखन उदाहरण

वर्ग र मेथडहरूमा पनिdocstringलाई लेख्न सिफारिस गरिन्छ। वर्गको लागिdocstringले वर्गले कस्ता कार्यहरू प्रदान गर्छ भन्ने संक्षिप्त रूपमा व्याख्या गर्छ, र प्रत्येक मेथडकोdocstringमा विशिष्ट कार्यहरूलाई विस्तृत रूपमा वर्णन गरिन्छ।
class Calculator:
    """
    सरल क्याल्कुलेटर वर्ग।

    यो वर्गले आधारभूत जोड, घटाउ, गुणा, भाग कार्यहरू गर्दछ।

    Attributes:
        result (int): गणनाको परिणाम राख्ने चल
    """

    def __init__(self):
        """
        Calculator वर्गको कन्स्ट्रक्टर।
        प्रारम्भ गर्दा परिणामलाई 0 मा सेट गरिन्छ।
        """
        self.result = 0

    def add(self, a, b):
        """
        दुई संख्याहरूलाई जोडेर, परिणाम फिर्ता गर्दछ।

        Args:
            a (int): पहिलो संख्या
            b (int): दोस्रो संख्या

        Returns:
            int: दुई संख्याहरूको योग
        """
        self.result = a + b
        return self.result
यस वर्गको उदाहरणमा, वर्गको सम्पूर्ण विवरणसँगै, __init__ रadd मेथडहरूका लागि पनि अलग-अलगdocstringलेखिएका छन्। यसरी गर्दा, वर्गका प्रयोगकर्ताहरूले प्रत्येक मेथड कसरी काम गर्छ भन्ने सजिलै बुझ्न सक्छन्।

Sphinx प्रयोग गरेर दस्तावेज निर्माण

Sphinx प्रयोग गर्दा, docstringको आधारमा HTML वा PDF स्वरूपको दस्तावेज स्वचालित रूपमा उत्पन्न गर्न सकिन्छ। पहिलो चरणमा, Sphinx लाई प्रोजेक्टमा समावेश गरी, सेटिङ फाइल (conf.py) तयार गर्नुहोस्। त्यसपछि, make html कमाण्ड चलाएर, docstringबाट स्वचालित रूपमा HTML दस्तावेज उत्पन्न हुन्छ। तलको कमाण्डले Sphinx इन्स्टल गर्न सकिन्छ।
pip install sphinx
अर्को चरणमा, sphinx-quickstart कमाण्ड प्रयोग गरेर प्रोजेक्टलाई आरम्भ गरी, प्रोजेक्टको लागि उपयुक्त सेटिङहरू गर्नुहोस्। त्यसपछि, Python फाइलमा लेखिएका docstringलाई प्रतिबिम्बित गर्ने दस्तावेज स्वचालित रूपमा उत्पन्न गर्न सकिन्छ।

7. सामान्य त्रुटिहरू र तिनीहरूको समाधान तरिका

docstring लेख्दा, शुरुआतीहरूले सजिलै गर्ने गल्तीहरू हुन्छन्। यस भागमा, सामान्य त्रुटिहरू र तिनीहरूको समाधान विधिहरू व्याख्या गरिन्छ।

1. अस्पष्ट व्याख्या

docstring स्पष्ट र संक्षिप्त हुनुपर्छ, तर अस्पष्ट व्याख्याले पाठकलाई उद्देश्य बुझ्न सक्दैन। उदाहरणका लागि, तलको docstring अपर्याप्त छ।
def add(a, b):
    """दुई संख्याहरूलाई जोड्छ।"""
    return a + b
यस उदाहरणमा, आर्गुमेन्ट र रिटर्न मानको व्याख्या अभाव छ, कुन प्रकारको डेटा लिन्छ र केिर्ता गर्छ भन्ने अस्पष्ट छ। सुधारको उपायको रूपमा, तलको जस्तै लेख्न सकिन्छ।
def add(a, b):
    """
    दुई पूर्णांकहरूलाई जोडेर, नतिजा फिर्ता गर्छ।

    Args:
        a (int): पहिलो संख्या
        b (int): दोस्रो संख्या

    Returns:
        int: दुई संख्याहरूको योग
    """
    return a + b

2. आर्गुमेन्ट वा रिटर्न मानको असठीक विवरण

docstring भित्र, आर्गुमेन्ट र रिटर्न मानको विस्तृत व्याख्या नहुनुले प्रयोगकर्ताले फङ्सनलाई सही तरिकाले प्रयोग गर्न सक्दैन। विशेष गरी, फङ्सन जटिल भएमा, आर्गुमेन्टको प्रकार र अर्थ, रिटर्न मानको प्रकारलाई स्पष्ट रूपमा उल्लेख गर्नु महत्त्वपूर्ण छ।
def divide(a, b):
    """दुई संख्याहरूलाई भाग गर्छ।"""
    return a / b
यस उदाहरणमा, आर्गुमेन्ट र त्रुटि ह्यान्डलिंगको व्याख्या अभाव छ। तलको जस्तै लेखेर, प्रयोगकर्ताले फङ्सनको प्रयोग सही रूपमा बुझ्न सक्छ।
def divide(a, b):
    """
    दुई संख्याहरूलाई भाग गरी, नतिजा फिर्ता गर्छ। 0 ले भाग गर्दा ZeroDivisionError उत्पन्न हुन्छ।

    Args:
        a (float): भागिने संख्या
        b (float): भाग गर्ने संख्या

    Returns:
        float: भागफलको नतिजा

    Raises:
        ZeroDivisionError: 0 ले भाग गर्ने प्रयास गर्दा
    """
    if b == 0:
        raise ZeroDivisionError("0 ले भाग गर्न सकिँदैन")
    return a / b
यसरी, docstring मा पर्याप्त जानकारी समावेश गरेर, प्रयोगकर्ताले कुनै भ्रम बिना कोड प्रयोग गर्न सकून् भन्ने कुरा महत्त्वपूर्ण छ।

8. सारांश: docstring प्रयोग गरेर प्रभावकारी दस्तावेज़ निर्माण

यस लेखमा, हामीले Python को docstring को महत्व, यसको लेखन तरिका, शैली, र सर्वोत्तम अभ्यासहरू बारे व्याख्या गरेका छौं। docstring कोडको पढ्नयोग्यता र मर्मत सम्भार सुधार्न अत्यन्त महत्वपूर्ण छ, र PEP 257 को दिशानिर्देशहरू पालना गरेर, एकरूप दस्तावेज़ निर्माण गर्न सकिन्छ। अझै, doctest प्रयोग गरेर परीक्षण र Sphinx प्रयोग गरेर दस्तावेज़ निर्माण मार्फत docstring को उपयोग गर्ने तरिका पनि सिक्यौं। यसले कोडको गुणस्तर सुधार र विकास कार्यक्षमता वृद्धि गर्न अपेक्षा गर्न सकिन्छ।

PEP 257 मा आधारित एकरूप दस्तावेज़ निर्माण

PEP 257 Python मा docstring लेख्नको लागि आधिकारिक दिशानिर्देश हो, र यसलाई पालना गरेर एकरूप र पढ्न सजिलो दस्तावेज़ निर्माण गर्न सकिन्छ। विशेष गरी, सरल एक-लाइनको docstring र विस्तृत व्याख्या समावेश गर्ने बहु-लाइनको docstring बीच चयन गरेर, कोडको उद्देश्यलाई सही रूपमा सम्प्रेषण गर्न सकिन्छ।

doctest को उपयोगद्वारा नमूना कोडको परीक्षण

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

Sphinx प्रयोग गरेर दस्तावेज़को स्वचालित निर्माण

Sphinx जस्ता दस्तावेज़ निर्माण उपकरणहरू प्रयोग गर्दा, docstring बाट स्वचालित रूपमा HTML वा PDF स्वरूपको दस्तावेज़ उत्पन्न गर्न सकिन्छ। यसले म्यानुअल दस्तावेज़ निर्माणको मेहनत घटाउँछ, र सधैं नवीनतम कोडमा आधारित दस्तावेज़ प्रदान गर्न सम्भव बनाउँछ।
年収訴求