> For the complete documentation index, see [llms.txt](https://mominur.gitbook.io/mominur-notes/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mominur.gitbook.io/mominur-notes/random-topics/clean-code/comments.md).

# Comments

আমরা অনেক সময় মনে করি বেশি কমেন্ট মানেই Code Clean, কিন্তু Clean Code বইয়ের লেখক Robert C. Martin (aka Uncle Bob) স্পষ্ট বলেন:

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

### কেন কমেন্ট দরকার হতে পারে?

কমেন্ট তখন দরকার হয় যখন আপনার কোড দিয়ে সব কিছু বোঝানো সম্ভব নয়। যেমন:

* জটিল কোনো লজিক ব্যাখ্যা করতে
* অস্থায়ী সমাধান বা হ্যাক বুঝাতে
* কোনো external dependency বা API নিয়ে সতর্কতা জানাতে
* কোনো known issue বা TODO নোট রাখতে

### কখন কমেন্ট লিখবেন না?

#### ১. যখন কমেন্ট দিয়ে আপনি কোড ব্যাখ্যা করছেন

**খারাপ:**

```python
# add 1 to count
count = count + 1
```

এটা redundant comment — এর দরকার নেই।

#### ২. কোডের পরিবর্তন ইতিহাস লিখছেন

**খারাপ:**

```python
# updated by Mominur on 12 April, 2025
# changed logic for discount
```

এই ধরনের ইনফো Git বা version control system-এ রাখা উচিত, কোডে নয়।

#### ৩. কমেন্ট দিয়ে বাজে কোড আড়াল করছেন

**খারাপ:**

```python
# এটা একটু জটিল, সময় পেলে পরবর্তীতে Clean করব
result = calculate_discount_for_each_customer_with_special_rules(customers)
```

➡️ এটা পড়ে বোঝা যায় — আপনি জানেন কোডটা খারাপ, কিন্তু ফিক্স করছেন না।

### কখন কমেন্ট দরকার?

#### ১. জটিল লজিকের ব্যাখ্যা দিতে

```python
# এই ফাংশনটি leap year বের করার জন্য, কারণ প্রতি ৪ বছর পর ১ দিন বাড়ে, কিন্তু প্রতি ১০০ বছরে নয়, আবার ৪০০ বছরে হয়
def is_leap_year(year): ...
```

➡️ লজিকটা যতই পরিষ্কার হোক, এই ব্যাখ্যা কাজে লাগবে।

***

#### ২. TODO বা FIXME নোট রাখতে

```python
# TODO: পরে এখানে ব্যালান্স চেক করতে হবে
# FIXME: এই অংশে কোনো সময় negative amount আসছে, হ্যান্ডেল করতে হবে
```

➡️ এগুলো ডেভেলপারদের জন্য জরুরি সিগন্যাল।

***

#### ৩. কোডের সাইড-ইফেক্ট বা বিশেষ dependency জানাতে

```python
# External API এর থ্রটল লিমিট ১০০০/ঘণ্টা — তাই এখানে rate limiting যুক্ত করা হয়েছে
call_api_with_rate_limit()
```

➡️ এটি ভবিষ্যৎ ডেভেলপারদের বড় বিপদ থেকে বাঁচাতে পারে।

***

#### ৪. Hack বা workaround ব্যাখ্যা করতে

```python
# Hack: এখানে manual delay রাখা হয়েছে, কারণ upstream system মাঝে মাঝে সাড়া দিতে দেরি করে
time.sleep(2)
```

➡️ এমন হ্যাক future-proof হয় না, তাই ব্যাখ্যা দিয়ে রাখুন।

***

### খারাপ কমেন্ট বনাম  ভালো কমেন্ট — উদাহরণসহ

#### খারাপ:

```python
# loop through users
for user in users:
    # get user name
    name = user["name"]
```

এগুলা বোঝার মতো যথেষ্ট না, বরং Bad naming এর আলামত।

***

#### ভালো:

```python
# বয়স অনুসারে eligibility বের করা হচ্ছে, কারণ ১৮ বছরের নিচে ইউজারকে reject করতে হবে
def is_eligible(age):
    return age >= 18
```

***

### Best Comment = No Comment

যদি আপনি কোড এতটাই পরিষ্কারভাবে লিখেন, যেখানে কমেন্টের দরকারই পড়ে না, তাহলেই আপনি একজন প্রকৃত ক্লিন কোডার।

Best Comment লেখার নিয়ম হলো —

> **Do not comment bad code, rewrite it.**

***

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

<table><thead><tr><th width="62">#</th><th width="292">ভালো অভ্যাস</th><th>ব্যাখ্যা</th></tr></thead><tbody><tr><td>1</td><td>ব্যাখ্যামূলক কমেন্ট</td><td>জটিল লজিক থাকলে ব্যাখ্যা দিন</td></tr><tr><td>2</td><td>TODO, FIXME, NOTE</td><td>কাজ বাকি বা ত্রুটি থাকলে ট্যাগ ব্যবহার করুন</td></tr><tr><td>3</td><td>External dependency এর সতর্কতা</td><td>API, DB, Caching এর মতো বিষয়ে নোট দিন</td></tr><tr><td>4</td><td>Avoid noise comments</td><td>obvious বা বোঝা যায় এমন জিনিস কমেন্ট করবেন না</td></tr><tr><td>5</td><td>Don't explain bad names</td><td>খারাপ নাম দিয়ে কমেন্ট লিখবেন না, বরং নাম ঠিক করুন</td></tr></tbody></table>

***

### BONUS: কমেন্টের পরিবর্তে যা করতে পারেন

✅ ফাংশনের নাম আরও অর্থবোধক করুন\
✅ ভ্যারিয়েবল নাম meaningful রাখুন\
✅ কোড ছোট ছোট ব্লকে ভাঙুন\
✅ ব্লক ফাংশনে split করুন যাতে সহজে test করা যায়