اصول کلین کد؛ راهنمای عملی نوشتن کد تمیز و قابلنگهداری
کلین کد یعنی کدی که دیگران راحت بخوانند و تغییر دهند؛ نامگذاری، توابع کوچک، مدیریت خطا، کامنت درست و بازآرایی را با مثالهای پایتون یاد بگیرید.

فهرست مطالب
- کلین کد چیست و چرا اهمیت دارد؟
- نامگذاری معنادار
- توابع کوچک با یک مسئولیت
- بازآرایی یک تابع واقعی: قبل و بعد
- شرطهای تودرتو را صاف کنید
- کامنت: چرا، نه چه
- تکرار نکنید، اما زود هم انتزاع نسازید
- مدیریت خطا بدون پنهانکاری
- اصول SOLID به زبان ساده
- فرمت و لینت را به ابزار بسپارید
- تست، شبکهی ایمنی بازآرایی
- کلین کد در دوران دستیارهای هوش مصنوعی
- چکلیست بازبینی کد تمیز
- جمعبندی
کلین کد (Clean Code) یعنی کدی که فقط کار نمیکند، بلکه دیگران هم میتوانند آن را سریع بخوانند، بفهمند و بدون ترس تغییر دهند. این اصطلاح با کتاب مشهور رابرت سی. مارتین رایج شد، اما ایدهاش ساده و قدیمی است: بیشتر عمر یک نرمافزار صرف نگهداری آن میشود، نه نوشتن نسخهی اول. در این راهنما اصول عملی کد تمیز را با مثالهای پایتون مرور میکنیم؛ اصولی که در هر زبانی کاربرد دارند.
کلین کد چیست و چرا اهمیت دارد؟
در راهنمای سبک رسمی پایتون، PEP 8، یکی از بینشهای کلیدی گیدو ون روسوم، خالق پایتون، اینطور نقل شده است: کد بسیار بیشتر از آنکه نوشته شود، خوانده میشود. هر بار که باگی را رفع میکنید یا قابلیتی اضافه میکنید، اول باید کد موجود را بفهمید.
مارتین فاولر این هزینه را با استعارهی بدهی فنی (Technical Debt) توضیح میدهد: کیفیت پایین داخلی مثل وام است و «بهرهاش» زمان اضافهای است که هر تغییر بعدی میگیرد. نکتهی ظریف حرف فاولر این است که این بهره فقط وقتی پرداخت میشود که به آن کد دست بزنید؛ پس تمیز نگه داشتن بخشهایی که زیاد تغییر میکنند، بیشترین سود را دارد.
نامگذاری معنادار
نام خوب نیمی از مستندات است. مقایسه کنید:
# Hard to read
d = 30
lst = get(u)
# Self-explanatory
trial_period_days = 30
unpaid_invoices = fetch_unpaid_invoices(customer)
چند قاعدهی عملی:
- نیت را بگویید، نه نوع را:
usersبهتر ازuser_listاست وactive_usersاز هر دو بهتر. - مقدارهای بولی را سؤالی نام بگذارید:
is_active،has_permission،can_publish. - از مخففهای شخصی پرهیز کنید:
cstmr_mgrرا فقط نویسندهاش میفهمد. - واژگان یکدست داشته باشید: اگر در یک جا
fetchنوشتید، جای دیگر برای همان کارgetوretrieveننویسید. - از قرارداد زبان پیروی کنید: در پایتون طبق PEP 8 نام توابع و متغیرها با حروف کوچک و خط زیر (
snake_case) و نام کلاسها باCapWordsنوشته میشود.
طول نام هم باید با دامنهی استفادهاش متناسب باشد. شمارندهی یک حلقهی سهخطی میتواند i باشد، اما متغیری که در چند تابع و فایل دیده میشود، به نامی کامل و توصیفی نیاز دارد. اگر برای یک تابع نام مناسبی پیدا نمیکنید، معمولاً نشانهی آن است که تابع بیش از یک کار انجام میدهد.
توابع کوچک با یک مسئولیت
تابعی که هم داده را اعتبارسنجی میکند، هم در پایگاه داده ذخیره میکند و هم ایمیل میفرستد، سه دلیل برای تغییر دارد و تست کردنش سخت است. هر تابع باید یک کار را خوب انجام دهد.
راهنمای سبک پایتون گوگل عدد مشخصی میدهد: اگر تابعی از حدود ۴۰ خط بیشتر شد، فکر کنید آیا میشود آن را بدون آسیب به ساختار برنامه شکست. این یک قانون خشک نیست، اما زنگ خطر خوبی است. تعداد پارامترها هم مهم است؛ تابعی با شش پارامتر معمولاً یعنی چند مفهوم باید در یک ساختار داده کنار هم قرار بگیرند.
بازآرایی یک تابع واقعی: قبل و بعد
این تابع کار میکند، اما خواندنش عذاب است:
def calc(d):
t = 0
for i in d:
if i["t"] == "b":
t += i["p"] * i["q"] * 0.9
else:
t += i["p"] * i["q"]
if t > 1000000:
t = t - 50000
return t
d، t و i چیزی نمیگویند، "b" معلوم نیست یعنی چه و 0.9 و 1000000 عدد جادویی (Magic Number) هستند. با چند بازآرایی (Refactoring) ساده از کاتالوگ فاولر، یعنی تغییر نام متغیر، جایگزینی عدد جادویی با ثابت و استخراج تابع، به این میرسیم:
WHOLESALE_DISCOUNT = 0.10
LARGE_ORDER_THRESHOLD = 1_000_000
LARGE_ORDER_REBATE = 50_000
def line_total(item: dict) -> float:
subtotal = item["price"] * item["quantity"]
if item["customer_type"] == "wholesale":
return subtotal * (1 - WHOLESALE_DISCOUNT)
return subtotal
def order_total(items: list[dict]) -> float:
total = sum(line_total(item) for item in items)
if total > LARGE_ORDER_THRESHOLD:
total -= LARGE_ORDER_REBATE
return total
منطق محاسبه در دو نسخه یکی است و فقط کلیدها و مقدارهای داده نامهای گویاتری گرفتهاند. اما حالا کد خودش میگوید چه قانونی را پیاده میکند، اگر نرخ تخفیف عوض شود فقط یک خط تغییر میکند و line_total را میشود جداگانه تست کرد.
یک نکتهی دیگر: این مثال برای سادگی از float استفاده میکند، اما در کد واقعی مبالغ پولی را با Decimal یا عدد صحیح (مثلاً به ریال) نگه دارید تا خطای گرد کردن اعشار در جمعها دیده نشود.
شرطهای تودرتو را صاف کنید
شرطهای چندلایه ذهن خواننده را خسته میکنند. با بند محافظ (Guard Clause) حالتهای استثنایی را زود برگردانید تا مسیر اصلی صاف بماند:
# Nested
def can_publish(article, user):
if article is not None:
if user.is_editor:
if article.status == "reviewed":
return True
return False
# Flat, with guard clauses
def can_publish(article, user):
if article is None:
return False
if not user.is_editor:
return False
return article.status == "reviewed"
کامنت: چرا، نه چه
کامنتی که همان کد را تکرار میکند، فقط نویز است و با اولین تغییر کد، دروغ میشود:
# Bad: repeats the code
i += 1 # increment i
# Good: explains a non-obvious decision
# The payment gateway rejects amounts with more than 2 decimals.
amount = round(amount, 2)
کامنت را برای چرایی تصمیمها، محدودیتهای بیرونی و هشدارها نگه دارید. کد کامنتشده را هم پاک کنید؛ Git تاریخچه را برایتان نگه میدارد.
تکرار نکنید، اما زود هم انتزاع نسازید
اصل DRY (Don't Repeat Yourself) میگوید هر دانش باید یک جا در کد تعریف شود. اما افراط در آن به انتزاعهای زودهنگام و پیچیده میرسد. قاعدهی عملی بسیاری از تیمها این است که بار سوم که الگویی تکرار شد، آن را به تابع یا ماژول مشترک تبدیل کنند. دو تکه کد شبیه هم که به دلایل متفاوت تغییر میکنند، لزوماً تکرار نیستند.
مدیریت خطا بدون پنهانکاری
- خطا را قورت ندهید:
except Exception: passباگ را پنهان میکند و عیبیابی را بسیار دشوار میکند. - خطای مشخص بگیرید: فقط استثنایی را بگیرید که میدانید چطور مدیریتش کنید.
- زود شکست بخورید: ورودی نامعتبر را همان ابتدای تابع رد کنید، نه سه لایه پایینتر.
- پیام خطا را کامل بنویسید: مقدار نامعتبر و انتظار درست را در پیام بگذارید.
اصول SOLID به زبان ساده
وقتی از سطح تابع به سطح کلاس و ماژول میرسید، پنج اصل مشهور به SOLID راهنمای خوبی برای طراحی تمیز است:
| اصل | معنای عملی |
|---|---|
| تکمسئولیتی (Single Responsibility) | هر کلاس یا ماژول فقط یک دلیل برای تغییر داشته باشد |
| باز و بسته (Open/Closed) | برای افزودن رفتار تازه، کد جدید اضافه کنید، نه اینکه کد پایدار را دستکاری کنید |
| جایگزینی لیسکوف (Liskov Substitution) | هر زیرکلاس باید بیدردسر جای کلاس والد بنشیند |
| تفکیک رابط (Interface Segregation) | بهجای یک رابط بزرگ، چند رابط کوچک و متمرکز بسازید |
| وارونگی وابستگی (Dependency Inversion) | منطق اصلی به انتزاع وابسته باشد، نه به جزئیاتی مثل یک پایگاه دادهی مشخص |
این اصول ابزار فکر کردناند، نه قانون. در یک اسکریپت صدخطی، پیادهسازی همهی آنها فقط پیچیدگی اضافه میکند. هرچه پروژه بزرگتر و تیم پرجمعیتتر شود، ارزششان بیشتر خودش را نشان میدهد؛ بهخصوص وارونگی وابستگی که تستنویسی را بسیار سادهتر میکند، چون میتوانید بهجای سرویس واقعی، نسخهی جعلی آن را به کد بدهید.
فرمت و لینت را به ابزار بسپارید
بحث دربارهی فاصله و جای آکولاد در بازبینی کد، وقت تلف کردن است. این کارها را به ابزار بسپارید:
| زبان | فرمتکننده | لینتر |
|---|---|---|
| Python | Black یا ruff format |
Ruff |
| JavaScript / TypeScript | Prettier | ESLint |
| Go | gofmt |
go vet |
این ابزارها را هم در ویرایشگر و هم در پایپلاین CI اجرا کنید تا کدی که قاعده را رعایت نمیکند، اصلاً ادغام نشود؛ آموزش CI/CD با GitHub Actions نحوهی راهاندازی آن را نشان میدهد.
تست، شبکهی ایمنی بازآرایی
بازآرایی یعنی تغییر ساختار کد بدون تغییر رفتار آن. بدون تست خودکار، راهی برای اطمینان از «بدون تغییر رفتار» ندارید. پیش از تمیز کردن یک بخش قدیمی، چند تست برای رفتار فعلیاش بنویسید، بعد با گامهای کوچک پیش بروید و بعد از هر گام تستها را اجرا کنید. هر گام را هم جداگانه در Git ثبت کنید تا اگر چیزی خراب شد، بدانید کدام تغییر مقصر بود.
قاعدهی پیشاهنگی (Boy Scout Rule) هم خلاصهی خوبی است: کد را کمی تمیزتر از زمانی که تحویل گرفتید، تحویل دهید.
کلین کد در دوران دستیارهای هوش مصنوعی
ابزارهای تولید کد با هوش مصنوعی سرعت نوشتن را بالا بردهاند، اما مسئولیت خوانایی و درستی کد همچنان با شماست. کدی را که دستیار پیشنهاد میدهد، مثل کد یک همتیمی تازهوارد بازبینی کنید: نامها، تکرارها و مدیریت خطا را بسنجید. در راهنمای بهترین ابزارهای هوش مصنوعی برای برنامهنویسی به نقاط قوت و ضعف این ابزارها پرداختهایم.
چکلیست بازبینی کد تمیز
| پرسش | اگر پاسخ «نه» است |
|---|---|
| نامها بدون کامنت منظور را میرسانند؟ | تغییر نام دهید |
| هر تابع یک کار انجام میدهد؟ | تابع را بشکنید |
| عدد یا رشتهی جادویی وجود ندارد؟ | ثابت با نام معنادار بسازید |
| تودرتویی شرطها بیشتر از دو سطح نیست؟ | از بند محافظ استفاده کنید |
| خطاها بیصدا نادیده گرفته نمیشوند؟ | خطای مشخص بگیرید یا بالا بفرستید |
| برای رفتار مهم تست وجود دارد؟ | پیش از ادغام تست بنویسید |
جمعبندی
کد تمیز محصول یک بازنویسی بزرگ نیست؛ نتیجهی عادتهای کوچکی است که هر روز تکرار میشوند. اگر تازه شروع کردهاید، مثالهای آموزش پایتون از صفر را با همین چکلیست بازنویسی کنید و تغییرات را با Git و GitHub ثبت کنید تا تفاوت قبل و بعد را ببینید.




دیدگاهها
دیدگاهها پس از بررسی تحریریه منتشر میشوند. توهین، تبلیغ و لینکهای بیربط حذف میشوند؛ نقد فنی و مستند همیشه خوشآمد است.
هنوز کسی چیزی ننوشته. اولین دیدگاه را شما ثبت کنید.