کد تمیز برای تازه‌کارها؛ از اسم‌گذاری تا توابع کوچک

سه ماه پیش کدی نوشتید؛ امروز برگشتید سراغش و ده دقیقه طول کشید بفهمید تابع calc2 چه می‌کند و flag کجا پر می‌شود. تبریک: شما به مهم‌ترین دلیل وجودِ «کد تمیز» (Clean Code) رسیده‌اید. کد تمیز ربطی به شیک‌بودن ندارد؛ یعنی کدی که برای انسانِ خواننده — هم‌تیمی، بازبین یا خودِ آیندهٔ شما — قابل فهم باشد. جملهٔ معروف این حوزه را حفظ کنید: کد، ده برابر بیشتر خوانده می‌شود تا نوشته.

برای تازه‌کارها این موضوع جدی‌تر از چیزی است که به نظر می‌رسد، چون اولین پروژه‌هایتان همان چیزی است که در گیت‌هاب به کارفرما نشان می‌دهید — و اولین چیزی که یک برنامه‌نویس باتجربه در کد شما می‌بیند، اسم‌هاست، نه معماری. این مطلب را می‌توانید هم‌زمان با ساختن پروژه‌های اولیهٔ برنامه‌نویسی تمرین کنید.

اسم‌گذاری؛ نصفِ خوانایی

بدترین اسم‌ها آن‌هایی‌اند که هیچ اطلاعات نمی‌دهند یا دروغ می‌گویند:

• data، temp، x2، finalFinal — هیچ چیز نمی‌گویند.
• اسمی که دروغ بگوید بدتر است: تابعی به نام getUser که کاربر را هم می‌گیرد، هم ذخیره می‌کند و هم اطلاع‌رسانی می‌کند.

قاعده‌های عملی:

• متغیر = اسم (چیست): userEmail، remainingItems، totalPrice — و اگر واحد مهم است، همراهش بیاورید: delayMs نه delay.
• تابع = فعل (چه می‌کند): sendEmail، calculateTax، filterActiveUsers. اگر اسم تابع به «و» نیاز دارد (processAndSaveAndNotify) یعنی تابع زیاد کار می‌کند.
• Boolean با is/has/did: isValid، hasPermission — شرط if (isValid) را می‌شود مثل جمله خواند.
• یک مفهوم، یک کلمه: اگر جایی fetch گفتید، جای دیگر get و load نگوید؛ خواننده حدس می‌کند تفاوتی هست و دنبالش می‌گردد.

توابع کوچک و تک‌منظوره

قاعدهٔ ساده: یک تابع، یک کار. وقتی مجبور شدید کارِ تابع را با «و» توصیف کنید، بشکافیدش:

// قبل: سه کارِ قاطی در یک تابع
function handleOrder(order) {
  // اعتبارسنجی + محاسبهٔ قیمت + ذخیره و اطلاع‌رسانی
}

// بعد: هر تابع یک کار؛ اسم‌ها خودشان توضیح می‌دهند
function validateOrder(order) { /* ... */ }
function calculateTotalPrice(order) { /* ... */ }
function saveOrderAndNotify(order) { /* ... */ }

فایده فقط خوانایی نیست: توابع کوچک، تست‌کردنشان ساده است، دوباره استفاده می‌شوند و باگ‌شان محلِ مشخصی دارد. به دنبال عدد جادویی (مثلاً «هیچ تابعی بیش از ۲۰ خط») نباشید؛ فقط این سؤال را بپرسید: «آیا این تابع دو کار می‌کند؟» اگر بله، دو تابع کنید.

تکرار نکنید خودتان را (DRY) — اما نه وسواسی

اگر یک منطق در سه جای کد کپی شده باشد، باگش را سه جا باید درست کنید — و همیشه یک جا یادتان می‌رود. قانون DRY (Don't Repeat Yourself) می‌گوید منطقِ یکسان را یک‌جا جمع کنید:

• رشته یا عددِ تکراری (مثل نرخ مالیات) ← یک ثابتِ بااسم: const TAX_RATE = 0.09.
• بلوکِ کدِ تکراری ← یک تابع.
• سه فرم با فیلدهای مشابه ← یک کامپوننتِ پارامتری.

اما تلهٔ تازه‌کار، برعکسِ DRY هم هست: خلاصه‌سازیِ زودهنگام. دو چیزِ مشابه که «هنوز» یکسان‌اند ولی به دلیل متفاوتی تغییر می‌کنند را زود یکی نکنید؛ دو کپیِ ساده گاهی تمیزتر از انتزاعِ غلط است. قانونِ عملی: دفعهٔ سومِ تکرار، وقتِ خلاصه‌سازی است (Rule of Three).

کامنت، فاصله و ساختار فایل

• کامنتِ «چرا» بنویسید نه «چه»: «قیمت را در ۰٫۰۹ ضرب می‌کنیم» بی‌فایده است چون کد خودش می‌گوید؛ «نرخ ۹٪ مالیات ارزش افزوده — مصوبهٔ ۱۴۰۳» ارزشمند است چون فقط از جنسِ چراست.
• کدی که برای فهمش کامنت لازم دارد را اول بازنویسی کنید: معمولاً اسم‌گذاری بهتر یا تابعِ کوچک‌تر، خودِ کامنت را حذف می‌کند.
• ساختارِ پیش‌فرض داشته باشید: فایل‌های هم‌نوع کنار هم، ترتیبِ ثابت داخل فایل (واردات، ثابت‌ها، توابع کمکی، تابع اصلی). یکدستی مهم‌تر از زیبایی است.
• قالب‌بندی را به ابزار بسپارید: Prettier یا فرمترِ خودِ ادیتور را فعال کنید تا فاصله‌ها و شکستن خطوط هیچ‌وقت موضوعِ بحث نباشند.

چک‌لیستِ ده‌ثانیه‌ای قبل از هر کامیت

قبل از commit این پنج سؤال را مرور کنید:

۱. اگر فردا برگردم، بدون توضیحِ اضافه می‌فهمم؟ ۲. اسمی هست که دروغ بگوید؟ ۳. تابعی هست که دو کار کند؟ ۴. عدد یا رشتهٔ جادوییِ بی‌اسم دارد؟ ۵. کامنتی هست که «چه» را توضیح دهد؟ (حذفش کنید)

این چک‌لیست همراهِ گیت و گیت‌هاب از صفر و عادتِ کامیت‌های کوچک، کیفیت کد شما را طی دو سه ماه جهش می‌دهد. و یادتان باشد کدِ تمیز در نهایت یک مهارت ارتباطی است: کد، پیامِ شما به خواننده است — همان اصولی که در مهارت‌های ارتباطی در محیط کار برای گفت‌وگو گفته‌ایم، این‌جا در متن کد معنا پیدا می‌کند.

سؤالات پرتکرار

وسط ساختن پروژه، چقدر روی تمیزکاری وقت بگذارم؟

قاعدهٔ عملی: اول کار کند، بعد تمیز شود. در جریانِ ساخت فقط اسم‌گذاریِ درست را رعایت کنید (هزینه‌اش صفر است) و بقیه — شکستنِ توابع، حذفِ تکرار — را به مرحلهٔ «سپری‌شدنِ پروژه» موکول کنید. تمیزکاریِ وسطِ کار، اگر بیش از حد شود، نوعی تعویقِ لذت‌بخش است.

آیا قواعد کد تمیز برای هر زبانی یکی است؟

اصل‌ها — اسمِ صادق، تابعِ کوچک، حذفِ تکرار، کامنتِ چرا — در همهٔ زبان‌ها یکی است؛ جزئیات مثل شیوهٔ نام‌گذاری (camelCase یا snake_case) و حداکثر طول خط، در راهنمای سبکِ هر زبان و هر تیم می‌آید. راهنماهای سبکِ گوگل که در پیوندهای پایین مطلب آمده، مرجع خوبی برای شروع است.

اگر در تیمی هستم که کدهایش تمیز نیست چه کنم؟

با نوکِ کدِ خودتان شروع کنید: کامیت‌های شما تمیز باشد و در بازبینیِ کد (Code Review) پیشنهادهای کوچک و مشخص بدهید، نه بازنویسیِ کل. برای نمونه‌کار هم همین کافی است که پروژه‌های شخصی‌تان تمیز باشند؛ ساخت پورتفولیو برای گرفتن مشتری کیفیت کد را هم می‌سنجد. و اگر جای این مهارت در کل مسیر یادگیری را می‌خواهید، نقشهٔ راه شش‌ماههٔ یادگیری برنامه‌نویسی نشانش می‌دهد.

ادامهٔ مسیر یادگیری

برای عمیق‌تر شدن در این موضوع، پیشنهاد می‌کنیم این مطالب را هم بخوانید:

یادگیری برنامه‌نویسی از صفر؛ نقشه راه شش‌ماهه تا اولین پروژه برنامه‌نویسی را از کجا شروع کنیم؟ نقشهٔ راه ۲۰۲۶ مصاحبه فنی برنامه‌نویسی؛ آمادگی کامل برای سؤالات کدنویسی سایت پورتفولیو برنامه‌نویس؛ ویترینی که مصاحبه می‌آورد پایتون یا جاوااسکریپت؟ مقایسهٔ کامل دو زبان محبوب در ۲۰۲۶