আমাকে অবশ্যই স্বীকার করতে হবে যে অন্যান্য উত্তরগুলি প্রস্তাবিত কিছু জিনিসের সাথে আমি একমত নই, তাই আমি আমার দুটি সেন্ট নিক্ষেপ করতে যাচ্ছি;
মন্তব্য
আপনার কোড পড়তে অপরিচিতদের জন্য ডকুমেন্টেশন চূড়ান্ত সহায়ক। সাধারণত অনেকগুলি পড়া এবং তাত্ক্ষণিকভাবে বোঝার জন্য যথেষ্ট পরিমাণে ভার্জোজ হবে না এবং তারপরে আপনি কী করছেন তা ব্যাখ্যা করা উচিত।
সম্পাদনা করুন : মন্তব্য বিভাগে আলোচনাটি সঠিক কিছু নির্দেশ করেছে - খারাপ কোড লেখার সময় সাধারণত অতিরিক্ত মন্তব্য করা হয় ।
আপনার কাজের মন্তব্যটি সুনির্দিষ্ট এবং ন্যূনতম হওয়া উচিত, তবে, আমার মতে, অবশ্যই উপস্থিত থাকা উচিত। কমপক্ষে 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
ন্যূনতম মন্তব্যগুলি যা আপনাকে বোঝায় যে কেন এবং কী করছেন তা পুরো কোড জুড়ে খুব সহায়ক। আমি যে উত্তর দিয়েছি তাতে রাজি নই
যদি আমি মন্তব্যযুক্ত কোডটি দেখতে পাই তবে আমি সবচেয়ে খারাপের জন্য প্রস্তুত: কোডটি সম্ভবত খারাপ হতে পারে, এবং সত্য কথা বলতে গেলে মন্তব্যগুলিও খারাপ হতে পারে।
অনেক সময়, করুণাময়, ভাল কোড নথিভুক্ত হয়। এটি সত্য যে খারাপ প্রোগ্রামাররা তাদের ডকুমেন্টেশনগুলি "ঠিক আছে, আমার কোডটি খারাপ, আসুন এটি পরিষ্কার করার জন্য কয়েকটি বাক্য যুক্ত করুন" see
হ্যাঁ, এবং এটি অনেকটা ঘটে গেলেও এটিও সত্য যে ক্লিন কোড লেখার ভাল প্রোগ্রামাররাও তাদের কোডটিতে ফিরে আসে এবং তারা কেন তাদের ফাংশনটি এরকম আচরণ করতে চায় তা বুঝতে নিশ্চিত করতে চায় বা তাদের কেন প্রয়োজন হয়েছিল? কিছুটা রিন্ডান্ট মনে হয় এমন লাইন ...
হ্যাঁ, মন্তব্যগুলি যা স্পষ্ট জিনিসগুলি ব্যাখ্যা করে, अस्पष्ट মন্তব্যগুলি, মন্তব্যগুলি যা "এই কোডটি নথিভুক্ত, হ্যাঁ, যাই হোক না কেন", কোড গন্ধ কিনা তা নিশ্চিত করার জন্য সবেমাত্র একত্র করা হয়েছিল। তারা কোড পড়া আরও কঠিন এবং বিরক্তিকর করে তোলে। (নীচে একটি উদাহরণ যোগ করা)
# Logging into Gmail when the module is imported
_client = login()
def get_client():
global _client
return _client
উদাহরণ স্পষ্টকরণ: "কোন ছিটেফেলা, শার্লক। _client = login()মেল পরিষেবাটিতে লগইন করে না? ওএমজি!"
আরও স্পষ্টতা: উপরোক্ত উদাহরণ থেকে পদ্ধতির 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()আপনার ব্যবহৃত সমস্ত কিছু দিয়ে প্যারামিটার সরবরাহ করতে হবে । কিছুটা সহায়তা করে তবে একটি জিনিস এখনও অনুপস্থিত।
ফাংশন ডকুমেন্টেশন
বহুল আলোচিত হয়েছে। আপনার ফাংশনটি কী, কেন এবং এটি কী করে তা আপনার পাঠকদের সর্বদা জানানো উচিত। এটি কীভাবে এটি করে, এটি ডকুমেন্টেশনের সাথে সম্পর্কিত নয়, তবে সম্ভবত ফাংশনটির পাদটীকাগুলি।
আপনার পরামিতিগুলি কী প্রত্যাশা করে তা আপনার স্পষ্টভাবে বর্ণনা করা উচিত এবং আপনি যদি কোনও নির্দিষ্ট পদ্ধতিতে সেগুলি অর্জন / তৈরি করতে চান তবে। আপনার ক্রিয়াকলাপটি কী ফিরে আসতে হবে, এর ব্যবহার কী হবে ইত্যাদি আপনার ঘোষণা করা উচিত etc.
আবার, আমার কোড লেখার সময় এটিই আমার মতামত এবং পদ্ধতি। কেবল সেগুলিই নয়, সেগুলি হ'ল কয়েকটি বিষয় যা সম্পর্কে আমি অন্যান্য উত্তরগুলির সাথে একমত হতে পারি না। ওহ, এবং অবশ্যই, মন্তব্যগুলি কেবল আপনার কোডটি পড়ে না, আপনার কোডটিও পড়ে। পরিষ্কার কোড লিখুন, বোধগম্য এবং রক্ষণাবেক্ষণযোগ্য । কোডিং করার সময় আপনার ভবিষ্যতের স্ব সম্পর্কে চিন্তা করুন ;-)