पायथन में कोड पर टिप्पणी कैसे करें

कार्यक्रम में टिप्पणियाँ कोड के वे भाग हैं जिन्हें दुभाषिए या संकलक द्वारा अनदेखा किया जाता है। उनकी आवश्यकता है:

• कोड को और अधिक पठनीय बनाने के लिए
• यह समझाने के लिए कि कोड क्या करता है और क्यों करता है
• कोड के किसी भाग को उसके परीक्षण/निष्पादन के दौरान निष्पादित होने से रोकने के लिए
• यह नोट करने के लिए कि क्या करने/फिर से करने/हटाने की आवश्यकता है

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

इस आलेख में, आप सीखेंगे कि Python 3 में टिप्पणियाँ कैसे छोड़नी हैं, Docstring और PEP क्या हैं।

Python में टिप्पणियाँ

विभिन्न प्रोग्रामिंग भाषाओं में टिप्पणियों के लिए अलग-अलग सिंटैक्स होते हैं। अक्सर, यह एक डबल स्लैश (//) होता है। Python 3 में, कोड में टिप्पणियाँ “#” चिह्न से शुरू होती हैं। उदाहरण के लिए:

#Code prints a line to the console "Hello, World!"
print("Hello, World!")

एक टिप्पणी को कोड वाली पंक्ति में भी रखा जा सकता है:

print("Hello, World!") #The code prints a string to the console "Hello, World!"

टिप्पणियाँ पाठक के लिए उपयोगी होनी चाहिए। उदाहरण के लिए, ऐसी टिप्पणी किसी काम की नहीं है:

#This code clearly does something
print("Hello, World!")

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

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

मान लीजिए कि हमें निम्नलिखित कोड को टिप्पणी देनी होगी:

db_lp = sqlite3.connect('login_password.db')
cursor_db = db_lp.cursor()
sql_create = '''CREATE TABLE passwords(
login TEXT PRIMARY KEY,
password TEXT NOT NULL);'''
cursor_db.execute(sql_create)
db_lp.commit()
cursor_db.close()
db_lp.close()

यह इस तरह से कमेंट किया जा सकता है:

db_lp = sqlite3.connect('login_password.db')  #Create database login_password
cursor_db = db_lp.cursor()  #Cursor class object for executing SQL queries
#SQL-request to create a password table in the database
sql_create = '''CREATE TABLE passwords(  
login TEXT PRIMARY KEY, 
password TEXT NOT NULL);''' 
cursor_db.execute(sql_create)  #Execute the query sql_create 
db_lp.commit()  #Confirm changes
#Close Cursor and database
cursor_db.close()   
db_lp.close()

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

• PyCharm: Ctrl + /;
• Visual Studio Code: लाइन कमेंट करने/अनकमेंट करने के लिए Ctrl + /, कोड ब्लॉक के लिए – Shift + Alt + A;
• Eclipse: लाइन कमेंट करने/अनकमेंट करने के लिए Ctrl + /, कोड ब्लॉक के लिए – Ctrl + Shift + /;
• Visual Studio: कोड ब्लॉक को कमेंट करने के लिए Ctrl + K फिर Ctrl + C, और कोड ब्लॉक को अनकमेंट करने के लिए Ctrl + K फिर Ctrl + U.

पायथन में Docstring

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

PEP क्या है?

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

चलिए Docstring पर वापस आते हैं। Docstring किसी ऑब्जेक्ट की घोषणा में पहला निर्देश है। यहाँ एक उदाहरण है:

def function (x,y,z): 
""" Docstring of this function""" 
def inner_function (): 
""" Docstring of the nested function """

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

ऑब्जेक्ट के docstring को doc विधि द्वारा एक्सेस किया जा सकता है:

def subtraction (a,b):     
"""The function subtracts number b from number a"""
    return (a-b) 
print(subtraction.__doc__)

परिणाम: फ़ंक्शन संख्या b को संख्या a से घटाता है।

doc विशेषता का उपयोग Python के अंतर्निहित तरीकों के बारे में जानकारी प्राप्त करने के लिए किया जा सकता है, जैसे कि प्रिंट करना:

print(print.__doc__)

निष्कर्ष:

print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False) 
Prints the values to a stream, or to sys.stdout by default.
Optional keyword arguments:
file:  a file-like object (stream); defaults to the current sys.stdout.
sep:   string inserted between values, default a space.
end:   string appended after the last value, default a newline.
flush: whether to forcibly flush the stream.

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

अतिरिक्त docstring

अतिरिक्त docstring स्ट्रिंग शाब्दिक हैं जिन्हें पायथन कंपाइलर द्वारा अनदेखा किया जाता है, लेकिन Docutils टूल द्वारा मान्यता प्राप्त हैं। इन्हें docstring के तुरंत बाद रखा जाता है। यहाँ एक उदाहरण है:

def function(arg):    
"""This is the docstring of this function. It will be available via the property  __doc__."""
"""
This is additional docstring, it will be ignored by the compiler, but recognized byDocutils.
"""
pass

विशेषता docstring

विशेषता docstring स्ट्रिंग शाब्दिक हैं जो मॉड्यूल, वर्ग या विधि init में सरल असाइनमेंट के तुरंत बाद आते हैं। उदाहरण के लिए:

def f(x):
"""This is the docstring of this function. It will be available via the property  __doc__"""
    return x**2
f.a = 1
""" This is attribute docstring for the attribute f.a of the function, it will be ignored by the compiler, but recognized by Docutils."""

Docstring का उपयोग करने के लिए PEP 257 की मुख्य सिफ़ारिशें निम्नलिखित हैं:

• प्रत्येक docstring के बाद एक खाली पंक्ति छोड़ें।
• Docstring स्क्रिप्ट को “उचित उपयोग” संदेश का प्रतिनिधित्व करना चाहिए, जिसे स्क्रिप्ट को ग़लत तर्कों के साथ कॉल करने पर उपयोगकर्ता को प्रदर्शित किया जा सकता है। Docstring को कार्यक्षमता, पैरामीटर सिंटैक्स, पर्यावरण चर और उपयोग की गई फ़ाइलों का वर्णन करना चाहिए।
• Docstring मॉड्यूल में महत्वपूर्ण ऑब्जेक्ट की सूची होनी चाहिए और उनमें से प्रत्येक के लिए एक-पंक्ति विवरण होना चाहिए।
• Docstring फ़ंक्शन या विधि को व्यवहार, तर्क, वापसी, संभावित अपवादों और संचालन संबंधी सीमाओं का वर्णन करना चाहिए।
• Docstring वर्ग को विधियों, इंस्टेंस चर और वर्ग के व्यवहार का वर्णन करना चाहिए।
• वर्ग कंस्ट्रक्टर के पास init पद्धति के लिए अपनी अलग Docstring पंक्ति होनी चाहिए।
• यदि वर्ग व्युत्पन्न है और इसका व्यवहार मुख्य रूप से आधार वर्ग से विरासत में मिला है, तो इसके Docstring को इसका उल्लेख करना चाहिए और संभावित अंतरों का वर्णन करना चाहिए।

उपयोगी उपकरण

निष्कर्ष के तौर पर, आइये उन उपकरणों की सूची देखें जो Python 3 में PEP 8 और कमेंट्री के साथ काम करने में सहायक होंगे:

• pycodestyle – आपके कोड को PEP 8 के अनुपालन के लिए जांचता है;
• Black – मुख्य रूप से PEP 8 के अनुसार आपके कोड को स्वरूपित करता है;
• Doxygen, PyDoc, pdoc – स्वचालित रूप से docstring से प्रलेखन उत्पन्न करते हैं