मुझे स्वीकार करना चाहिए कि मैं उन कुछ चीजों से सहमत नहीं हूं जिन्हें अन्य उत्तरों की सिफारिश की गई है, इसलिए मैं अपने दो सेंट फेंकने जा रहा हूं;
टिप्पणियाँ
आपके कोड को पढ़ने वाले अजनबियों के लिए प्रलेखन अत्यंत उपयोगी है। आमतौर पर कई चीजों को तुरंत पढ़ने और समझने के लिए पर्याप्त नहीं होगा, और आपको तब समझाना चाहिए कि आप क्या कर रहे हैं।
संपादित करें : टिप्पणी अनुभाग में चर्चा ने कुछ सही बताया है - खराब कोड लिखते समय आमतौर पर ओवर-कमेंटिंग की जाती है ।
आपके काम की टिप्पणी सटीक और न्यूनतम होनी चाहिए, लेकिन, मेरी राय में, निश्चित रूप से उपस्थित होना चाहिए। कोड की प्रत्येक 15 पंक्तियों के लिए कम से कम एक टिप्पणी। उदाहरण के लिए, कोड के ब्लॉक के शीर्ष पर, आप क्या कर रहे हैं, इसके बारे में एक पंक्ति जोड़ें:
def login(username: str, password: str, create_session: bool = True):
# Filter the user we need from the database
hash = md5(password)
users = db.table("users", db_entities.USER)
results = [x for x in users.query(lambda c: c.get("username") == username and c.get("password_hash") == hash)]
if len(results) == 0:
return None, None
else:
# Create a login session record in the database.
if create_session:
sessions = db.table("sessions", db_entities.SESSION)
ses = sessions.new()
ses.set("username", username) \
.set("expiery", 31536000 + time.time())
sessions.update(ses)
return results[0], ses
else:
return results[0], None
न्यूनतम टिप्पणियां जो बताती हैं कि आप क्यों और क्या कर रहे हैं, पूरे कोड में बहुत सहायक हैं। मैं उस उत्तर से सहमत नहीं हूं जो बताता है
यदि मुझे कोड युक्त टिप्पणियां आती हैं, तो मैं सबसे खराब तैयारी करता हूं: कोड खराब होने की संभावना है, और ईमानदार होने के लिए टिप्पणियों के भी खराब होने की संभावना है।
कई बार, सुशोभित, अच्छा कोड प्रलेखित होता है। यह सच है कि बुरे प्रोग्रामर अपने प्रलेखन को देखते हैं जैसे "ठीक है, मेरा कोड खराब है, चलो इसे स्पष्ट करने के लिए कुछ वाक्य जोड़ें"।
हां, और जबकि यह बहुत अधिक होता है, यह भी सच है कि अच्छे प्रोग्रामर जो क्लीन कोड लिखते हैं, वे यह भी सुनिश्चित करना चाहते हैं कि वे अपने कोड पर लौट आएं और समझें कि वे क्यों चाहते हैं कि उनका कार्य उस तरह का व्यवहार करे, या उन्हें इसकी आवश्यकता क्यों है लाइन जो थोड़ा बेमानी लगता है, आदि ...
हाँ, ऐसी टिप्पणियाँ जो स्पष्ट बातें समझाती हैं, टिप्पणियाँ जो अस्पष्ट हैं, टिप्पणियाँ जो केवल यह सुनिश्चित करने के लिए एक साथ रखी गई थीं कि "यह कोड प्रलेखित है, हाँ, जो भी हो", कोड गंध हैं। वे कोड को पढ़ना कठिन और परेशान करते हैं। (नीचे एक उदाहरण जोड़ते हुए)
# Logging into Gmail when the module is imported
_client = login()
def get_client():
global _client
return _client
उदाहरण स्पष्टीकरण: "नो शिट, शरलॉक। _client = login()मेल सेवा में लॉग इन करता है ? OMG!"
अधिक स्पष्टीकरण: login()विधि का login()उपरोक्त उदाहरण से विधि से कोई संबंध नहीं है ।
लेकिन जो टिप्पणियां मानकों से मेल खाती हैं, वे क्यों और कैसे नहीं की व्याख्या करती हैं, और सही सवालों का जवाब देती हैं, बहुत ( बहुत ) सहायक हैं।
इनलाइन टिप्पणी
एक बात जो आपको नहीं करनी चाहिए (और अगर मैं उस बड़े को लिख सकता था, तो मैं करूंगा), कोड की एक ही पंक्ति में अपनी टिप्पणी लिखूंगा। यह टिप्पणियों को बहुत लाइन-विशिष्ट बनाता है, जो आपके कोड को टिप्पणी करने के उद्देश्य को पूरी तरह से याद करता है।
उदाहरण के लिए, खराब इनलाइन टिप्पणियां:
outer = MIMEText(details["message"]) # Constructing a new MIMEText object
outer["To"] = details["to"] # Setting message recipient
outer["From"] = "xAI No-Reply" # Setting message sender
outer["Subject"] = details["subject"] # Setting message subject
outer.preamble = "You will not see this in a MIME-aware mail reader.\n" # I don't know what I'm doing here, I copied this from SO.
msg = outer.as_string() # Getting the string of the message
_client = details["client"] # Assigning the client
_client.sendmail(SENDER, details["to"], msg) # Sending the mail
टिप्पणियों के बिना इस कोड को पढ़ना और समझना बहुत आसान होगा, जो इसे गन्दा और अपठनीय बनाता है।
इसके बजाय, आपके कोड के अंदर टिप्पणियों को कोड पर ब्लॉक से ऊपर रखा जाना चाहिए, और उन्हें उन महत्वपूर्ण सवालों का जवाब देना चाहिए जो कोड ब्लॉक को पढ़ते समय उत्पन्न हो सकते हैं।
# Constructing the email object with the values
# we received from the parameter of send_mail(details)
outer = MIMEText(details["message"])
outer["To"] = details["to"]
outer["From"] = "xAI No-Reply"
outer["Subject"] = details["subject"]
outer.preamble = "You will not see this in a MIME-aware mail reader.\n"
msg = outer.as_string()
# Sending the mail using the global client (obtained using login())
_client = details["client"]
_client.sendmail(SENDER, details["to"], msg)
बहुत स्पष्ट है, है ना? अब आप यह भी जानते हैं कि आपको login()फ़ंक्शन का उपयोग करना होगा और send_mail()आपके द्वारा उपयोग की जाने वाली हर चीज के साथ पैरामीटर प्रदान करना होगा । थोड़ी मदद करता है, लेकिन एक चीज अभी भी गायब है।
समारोह प्रलेखन
व्यापक रूप से चर्चा की गई है। आपको हमेशा अपने पाठकों को यह बताना चाहिए कि आपका कार्य क्या है, क्यों और क्या करता है। यह कैसे होता है, यह प्रलेखन का नहीं है, लेकिन शायद फ़ंक्शन के फुटनोट्स का।
आपको स्पष्ट रूप से वर्णन करना चाहिए कि आप अपने मापदंडों के बारे में क्या उम्मीद करते हैं, और यदि आप चाहते हैं कि उन्हें एक विशिष्ट विधि में प्राप्त / बनाया जाए। आपको यह घोषित करना चाहिए कि आपका फ़ंक्शन क्या लौटना चाहिए, इसका उपयोग क्या है, आदि।
फिर से, मेरे कोड लिखते समय मेरी राय और कार्यप्रणाली। केवल वे ही नहीं, बल्कि वे ही कुछ ऐसी चीजें हैं जिनके बारे में अन्य उत्तरों से मैं सहमत नहीं हो सका। ओह, और निश्चित रूप से, न केवल टिप्पणियां आपके कोड को पढ़ती हैं, बल्कि आपका कोड भी। साफ कोड, समझ और बनाए रखने योग्य लिखें । कोडिंग के दौरान अपने भविष्य के बारे में सोचो; ;;