Comments

Clean Code এ কমেন্টের ব্যবহার: ভালো নাকি খারাপ?

অনেক সময় আমরা মনে করি, কোডে যত বেশি কমেন্ট থাকবে, কোডটি তত বেশি বোধগম্য বা 'Clean' হবে। কিন্তু "Clean Code" বইয়ের রচয়িতা রবার্ট সি. মার্টিন (Uncle Bob) এই ধারণাকে সম্পূর্ণ ভুল প্রমাণ করেছেন। তিনি স্পষ্টভাবে বলেছেন:

"Comments are always failures. We write them because we cannot make the code expressive enough."

অর্থাৎ, তুমি যখন তোমার কোড দিয়ে লজিক বা উদ্দেশ্য বোঝাতে ব্যর্থ হও, ঠিক তখনই তোমাকে কমেন্টের আশ্রয় নিতে হয়। একটি আদর্শ কোডবেসে কোড নিজেই নিজের ডকুমেন্টেশন হিসেবে কাজ করে।

কখন কমেন্ট লেখা থেকে বিরত থাকবে (Bad Comments)

অপ্রয়োজনীয় কমেন্ট কোডবেসে নয়েজ (Noise) তৈরি করে এবং কোড রিডেবিলিটি কমিয়ে দেয়। নিচের ক্ষেত্রগুলোতে কখনোই কমেন্ট ব্যবহার করা উচিত নয়:

• ১. কোড দিয়ে কোড ব্যাখ্যা করা (Noise Comments): কোড পড়ে যা সহজেই বোঝা যাচ্ছে, তা নিয়ে কমেন্ট করা সম্পূর্ণ অর্থহীন।

• ২. বাজে কোড আড়াল করা: লজিক অগোছালো বা ফাংশনের নাম খারাপ দিয়ে পরে কমেন্ট দিয়ে তা বোঝানোর চেষ্টা করা। মনে রাখবে: "Do not comment bad code, rewrite it."

• ৩. কোডের পরিবর্তন বা ইতিহাস লেখা (Journal Comments): কে, কবে, কেন কোড এডিট করেছে—এসব তথ্য ফাইলে লিখে রাখা উচিত নয়। এগুলোর জন্য Git বা ভার্সন কন্ট্রোল সিস্টেম (VCS) রয়েছে।

• ৪. কমেন্ট আউট করা কোড (Zombie Code): পুরোনো লজিক বা ফাংশন মুছে ফেলার বদলে কমেন্ট করে রেখে দেওয়া একটি বাজে অভ্যাস। গিট তো আছেই পুরোনো কোড ফিরিয়ে আনার জন্য, তাই অপ্রয়োজনীয় কোড ডিলিট করে দেওয়াই শ্রেয়।

কখন কমেন্ট লেখা জরুরি (Good Comments)

সব কমেন্টই খারাপ নয়। কিছু নির্দিষ্ট পরিস্থিতিতে কমেন্ট লেখা সফটওয়্যার ইঞ্জিনিয়ারিংয়ের জন্য অপরিহার্য:

• ১. পেছনের উদ্দেশ্য বা লজিক ব্যাখ্যা করতে (Explanation of Intent): কোড "কী" করছে তা কোড দেখলেই বোঝা যায়, কিন্তু "কেন" করছে (Why) তা বোঝাতে কমেন্ট দরকার হয়। (যেমন: লিপ ইয়ারের জটিল হিসাবের পেছনের কারণ)।

• ২. ভবিষ্যতের কাজ মনে রাখতে (TODO / FIXME): প্রজেক্টের কোনো অসম্পূর্ণ কাজ বা জানা কোনো বাগ ফিক্স করার জন্য এই সিগন্যালগুলো টিমের অন্যান্য ডেভেলপারদের সতর্ক করে।

• ৩. সাইড-ইফেক্ট বা সতর্কতা জানাতে (Warning of Consequences): কোনো নির্দিষ্ট ফাংশন কল করলে সিস্টেমে কী নেতিবাচক প্রভাব পড়তে পারে (যেমন: থার্ড-পার্টি এপিআইয়ের রেট লিমিট, বা কোনো ডেটাবেস লক), তা জানাতে কমেন্ট ব্যবহার করা উচিত।

• ৪. হ্যাক বা সাময়িক সমাধান (Workarounds/Hacks): কোনো লাইব্রেরির বাগ বা আপস্ট্রিম সিস্টেমের কারণে যদি সাময়িক বা অদ্ভুত কোনো লজিক (যেমন: sleep ব্যবহার করা) লিখতে হয়, তবে তার যথাযথ ব্যাখ্যা কমেন্টে থাকা উচিত।

খারাপ কমেন্ট বনাম ভালো কমেন্ট: কোড উদাহরণ

নিচে পাইথন ব্যবহার করে খারাপ এবং ভালো কমেন্টের পার্থক্য দেখানো হলো:

# ---------------------------------------------------------
# BAD CODE (Noise comments and masking bad naming)
# ---------------------------------------------------------

# loop through the users list
for u in users_list:
    # check if age is greater than 18 and status is 1
    if u.a > 18 and u.s == 1:
        # append to valid list
        v_list.append(u)

# TODO: fix this later, very slow performance
result = complex_calculation_with_nested_loops(v_list)


# ---------------------------------------------------------
# CLEAN CODE (Expressive code with meaningful comments)
# ---------------------------------------------------------

ACTIVE_STATUS = 1

def is_eligible_for_loan(user_age: int, user_status: int) -> bool:
    return user_age >= 18 and user_status == ACTIVE_STATUS

for user in users_list:
    if is_eligible_for_loan(user.age, user.status):
        valid_users.append(user)

def fetch_data_from_legacy_system():
    # WARNING: The legacy upstream system can only handle 5 requests per second.
    # Removing this manual delay will result in IP ban from their firewall.
    time.sleep(0.2) 
    
    # FIXME: Sometimes the legacy API returns negative amounts, need to handle parsing safely.
    pass

কমেন্ট লেখার সংক্ষিপ্ত গাইডলাইন

কমেন্টের বিকল্প: কোডকে কীভাবে আরও এক্সপ্রেসিব করবে?

সবচেয়ে ভালো কমেন্ট হলো— কোনো কমেন্ট না থাকা। তুমি যদি নিচের নিয়মগুলো মানতে পারো, তবে তোমার কোডে কমেন্টের প্রয়োজন অর্ধেকের বেশি কমে যাবে:

• Meaningful Naming: ভ্যারিয়েবল ও ফাংশনের নাম এমন দাও যা নিজেই পুরো গল্পের সারমর্ম বলে দেয়।

• Extract Variable (ভ্যারিয়েবল আলাদা করা): জটিল কোনো if কন্ডিশনকে সরাসরি if এর ভেতর না লিখে, একটি সুন্দর নামের বুলিয়ান ভ্যারিয়েবলে অ্যাসাইন করে তারপর ব্যবহার করো।

• Small Functions: বড় কোড ব্লককে ছোট ছোট ফাংশনে (Helper functions) ভাগ করো। ফাংশনের নামটাই তখন কমেন্টের কাজ করবে।