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

वाक्य - विन्यास

• # यह एक सिंगल लाइन टिप्पणी है
• प्रिंट ("") # यह एक इनलाइन टिप्पणी है
• "" "
  ये है
  एक बहु-पंक्ति टिप्पणी
  "" "

टिप्पणियों

सिंगल लाइन, इनलाइन और मल्टीलाइन टिप्पणियाँ

जब मूल कोड ही स्पष्ट नहीं होता है, तो कोड को समझाने के लिए टिप्पणियों का उपयोग किया जाता है।

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

सिंगल-लाइन टिप्पणियां हैश चरित्र ( # ) से शुरू होती हैं और लाइन के अंत तक समाप्त हो जाती हैं।

• एकल पंक्ति टिप्पणी:

# This is a single line comment in Python

• इनलाइन टिप्पणी:

print("Hello World")  # This line prints "Hello World"

• कई पंक्तियों में फैली टिप्पणियों में दोनों छोर पर """ या ''' । यह एक बहु-तार स्ट्रिंग के समान है, लेकिन उनका उपयोग टिप्पणियों के रूप में किया जा सकता है:

"""
This type of comment spans multiple lines.
These are mostly used for documentation of functions, classes and modules.
"""

प्रोग्रामेटिक रूप से डोकस्ट्रिंग्स को एक्सेस करना

Docstrings हैं - नियमित टिप्पणियों के विपरीत - फ़ंक्शन के एक विशेषता के रूप में संग्रहीत, वे दस्तावेज़, जिसका अर्थ है कि आप उन्हें प्रोग्रामेटिक रूप से एक्सेस कर सकते हैं।

एक उदाहरण समारोह

def func():
    """This is a function that does nothing at all"""
    return

__doc__ को __doc__ विशेषता का उपयोग करके एक्सेस किया जा सकता है:

print(func.__doc__)

यह एक ऐसा फंक्शन है जो कुछ भी नहीं करता है

help(func)

समारोह पर सहायता func मॉड्यूल में __main__ :

func()

यह एक ऐसा फंक्शन है जो कुछ भी नहीं करता है

एक और उदाहरण समारोह

function.__doc__ एक स्ट्रिंग के रूप में केवल वास्तविक function.__doc__ है, जबकि help फ़ंक्शन function.__doc__ सहित किसी फ़ंक्शन के बारे में सामान्य जानकारी प्रदान करता है। यहाँ एक और सहायक उदाहरण दिया गया है:

def greet(name, greeting="Hello"):
    """Print a greeting to the user `name`

    Optional parameter `greeting` can change what they're greeted with."""
    
    print("{} {}".format(greeting, name))

help(greet)

समारोह पर सहायता greet मॉड्यूल में __main__ :

greet(name, greeting='Hello')

उपयोगकर्ता name लिए एक ग्रीटिंग प्रिंट करें
वैकल्पिक पैरामीटर greeting को वे बदल सकते हैं जो उनके साथ अभिवादन करते हैं।

नियमित टिप्पणियों पर docstrings के लाभ

किसी फ़ंक्शन में कोई डॉकस्ट्रिंग या एक नियमित टिप्पणी नहीं डालना, यह बहुत कम सहायक बनाता है।

def greet(name, greeting="Hello"):
    # Print a greeting to the user `name`
    # Optional parameter `greeting` can change what they're greeted with.
    
    print("{} {}".format(greeting, name))

print(greet.__doc__)

कोई नहीं

help(greet)

मॉड्यूल मुख्य में फ़ंक्शन ग्रीटिंग पर मदद:

greet(name, greeting='Hello')

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

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

def hello(name):
    """Greet someone.

    Print a greeting ("Hello") for the person with the given name.
    """

    print("Hello "+name)

class Greeter:
    """An object used to greet people.

    It contains multiple greeting functions for several languages
    and times of the  day.
    """

डॉकस्ट्रिंग के मूल्य को प्रोग्राम के भीतर एक्सेस किया जा सकता है और उदाहरण के लिए - help कमांड द्वारा उपयोग किया जाता है।

सिंटेक्स सम्मेलनों

पीईपी 257

पीईपी 257 डॉकस्ट्रिंग टिप्पणियों के लिए एक वाक्यविन्यास मानक को परिभाषित करता है। यह मूल रूप से दो प्रकार की अनुमति देता है:

• एक-पंक्ति डॉकस्ट्रिंग्स:

पीईपी 257 के अनुसार, उन्हें छोटे और सरल कार्यों के साथ उपयोग किया जाना चाहिए। सब कुछ एक पंक्ति में रखा जाता है, जैसे:

def hello():
    """Say hello to your friends."""
    print("Hello my friends!")

डॉकस्ट्रिंग एक अवधि के साथ समाप्त हो जाएगी, क्रिया अनिवार्य रूप में होनी चाहिए।

• मल्टी-लाइन डॉकस्ट्रिंग्स:

मल्टी-लाइन डॉकस्ट्रिंग का उपयोग लंबे, अधिक जटिल कार्यों, मॉड्यूल या कक्षाओं के लिए किया जाना चाहिए।

def hello(name, language="en"):
    """Say hello to a person.

    Arguments:
    name: the name of the person
    language: the language in which the person should be greeted
    """

    print(greeting[language]+" "+name)

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

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

गूढ़ व्यक्ति

स्फिंक्स डॉकस्ट्रिंग्स पर आधारित पायथन परियोजनाओं के लिए HTML आधारित प्रलेखन उत्पन्न करने के लिए एक उपकरण है। इसके मार्कअप भाषा का प्रयोग किया है reStructuredText । वे प्रलेखन के लिए अपने स्वयं के मानकों को परिभाषित करते हैं, pythonhosted.org उनके बारे में बहुत अच्छा वर्णन करता है । Sphinx प्रारूप pyCharm IDE द्वारा उपयोग किए गए उदाहरण के लिए है।

Sphinx / reStructuredText प्रारूप का उपयोग करके एक फ़ंक्शन इस तरह से प्रलेखित किया जाएगा:

def hello(name, language="en"):
    """Say hello to a person.

    :param name: the name of the person
    :type name: str
    :param language: the language in which the person should be greeted
    :type language: str
    :return: a number
    :rtype: int
    """

    print(greeting[language]+" "+name)
    return 4

Google पायथन स्टाइल गाइड

Google ने Google Python स्टाइल गाइड प्रकाशित किया है, जो प्रलेखन टिप्पणियों सहित पायथन के लिए कोडिंग सम्मेलनों को परिभाषित करता है। स्फिंक्स / रेस्ट की तुलना में कई लोग कहते हैं कि Google के दिशानिर्देशों के अनुसार प्रलेखन बेहतर मानव पठनीय है।

ऊपर उल्लिखित pythonhosted.org पेज गूगल स्टाइल गाइड के अनुसार अच्छे प्रलेखन के लिए कुछ उदाहरण भी प्रदान करता है।

नेपोलियन प्लगइन का उपयोग करते हुए, स्फ़िंक्स Google स्टाइल गाइड-अनुपालन प्रारूप में प्रलेखन को पार्स भी कर सकता है।

Google शैली गाइड प्रारूप का उपयोग करके एक फ़ंक्शन इस तरह से प्रलेखित किया जाएगा:

def hello(name, language="en"):
    """Say hello to a person.

    Args:
        name: the name of the person as string
        language: the language code string

    Returns:
        A number.
    """

    print(greeting[language]+" "+name)
    return 4