اسم‌گذاری متغیرها در کد؛ راهنمای نوشتن کد خوانا بدون توضیح

چرا اسم‌گذاری مهم‌ترین مهارت کوچک کدنویسی است؟

کد خیلی بیشتر از آنکه نوشته شود، خوانده می‌شود؛ توسط خود شما هفتهٔ بعد، توسط همکارتان برای رفع باگ و توسط مصاحبه‌گر بعدی شما. در این خواندن‌ها، چیزی که بیشترین وقت را می‌گیرد فهمِ اینکه هر متغیر «چی هست» است. اسم خوب مثل تابلوئی است که روی جعبه چسبانده‌اید؛ اسم بد مثل جعبهٔ بی‌برچسب در انباری تاریک. هنرمندانه اسم‌گذاری کردن، ساده‌ترین و ارزان‌ترین راه بالا بردن کیفیت کد است، بدون حتی یک خط تغییر منطق.

تجربهٔ همهٔ برنامه‌نویسان حرفه‌ای این را تأیید می‌کند: بخش بزرگی از دیباگ صرف فهمیدن کدی می‌شود که خودشان ماه‌ها پیش نوشته‌اند. وقتی اسم‌ها گویا باشند، دیباگ سریع‌تر می‌شود، بازبینی کد روان‌تر پیش می‌رود و اضافه‌شدن عضو جدید به تیم، به‌جای هفته‌ها سرگشتگی، چند روزه جا می‌افتد. اشتباهات سال اول برنامه‌نویسی هم تقریباً همیشه فهرستی از اسم‌های مبهم در دل خود دارند.

قواعد عملی برای انواع اسم

• بولین‌ها با is یا has یا can شروع شوند: isLoading، hasDiscount، canEdit؛ خوانندهٔ کد از همان اول می‌داند مقدار درست/غلط است.
• توابع با فعل شروع شوند: sendInvoice، calculateTotal؛ تابع یک کار است و اسمش باید همان کار را بگوید.
• از اسم‌های عمومی بی‌خاصیت فرار کنید: data، temp، info، handler2 هیچ اطلاعاتی نمی‌دهند؛ invoiceData بهتر است و paidInvoices حتی بهتر.
• مجموعه‌ها جمع باشند: users به‌جای userList یا بدتر، arr؛ اگر نوع مهم است، userNames بگویید.
• ثابت‌ها معنادار نام‌گذاری شوند: به‌جای const x = 86400 بنویسید const SECONDS_PER_DAY = 86400؛ عدد و معنایش در یک جا.

یک قاعدهٔ طلایی هم برای طول اسم‌ها: اسم به‌اندازهٔ کافی بلند باشد که معنا بدهد و به‌اندازهٔ کافی کوتاه که خوانده شود؛ targetUserEmail عالی است، theEmailAddressOfTheUserThatWeWantToSendTo دیگر کمدی است.

قبل و بعد: بازنویسی چند مثال واقعی

تفاوت را در چند نمونهٔ واقعی ببینید؛ اول نسخهٔ مبهم و بعد نسخهٔ گویا:

const d = 3;                    // قبل: d چیست؟ روز؟ تخفیف؟
const maxRetryAttempts = 3;    // بعد: واضح و بی‌نیاز از توضیح

function handle(x) { }         // قبل: handleِ چه چیزی؟
function sendInvoiceEmail(invoice) { } // بعد

همین دو تغییر کوچک، بدون هیچ کامنتی، کد را خودتوضیح‌گر کرد. حالا یک مثال فارسی از دنیای واقعی: در پروژهٔ فروشگاهی، متغیری به نام list وجود داشت که بعد از چهل دقیقه جست‌وجو معلوم شد «فهرست سفارش‌های لغوشدهٔ سی روز اخیر» است؛ اسم درستش recentCancelledOrders بود. آن چهل دقیقه، هزینهٔ واقعیِ اسم بد است و هر تیمی، هر هفته چند بار آن را پرداخت می‌کند.

اسم‌های دروغگو؛ خطرناک‌ترین نوع

از اسم مبهم بدتر، اسم دروغگوست؛ اسمی که معنایی غیر از واقعیتِ کد می‌دهد. تابعی به نام getUser که همزمان کاربر را در دیتابیس هم ذخیره می‌کند، دروغ می‌گوید. متغیری به نام items که در واقع فقط یک آیتم است، دروغ می‌گوید. فهرستی به نام activeUsers که کاربران حذف‌شده را هم دارد، دروغ می‌گوید. این‌ها خطرناک‌اند چون خواننده با اعتماد به اسم، دنبال باگ در جای اشتباه می‌گردد.

نوع شایع دیگر، اسم‌های قدیمی‌شده است: کدی با searchResults شروع می‌کند، ماه‌ها بعد منطقش به «پیشنهادها» تغییر می‌کند اما اسم همان می‌ماند و حالا دروغگوی رسایی است. قاعدهٔ ساده: هر وقت منطق را عوض کردید، یک ثانیه روی اسمش فکر کنید؛ اگر اسم دیگر واقعیت را نمی‌گوید، همان لحظه عوضش کنید. این بخش جدانشدنی از نگه‌داشتن کد تمیز در طول عمر پروژه است.

فرهنگ اسم‌گذاری در تیم

اسم‌گذاری در تیم، از قواعد فردی فراتر می‌رود و به قراردادهای مشترک نیاز دارد. اول، قرارداد نگارشی هر زبان را رعایت کنید: camelCase در جاوااسکریپت، snake_case در پایتون؛ مخلوط‌کردن این‌ها، خواندن را دائماً لنگ می‌کند. دوم، برای مفاهیم تخصصی حوزهٔ کسب‌وکارتان یک واژه‌نامهٔ کوچک بسازید: اگر در تیم «سفارش» را order می‌نامیدید، هیچ‌کس نباید جایی purchase بگذارد؛ همین یکدستی واژگان، نصف سردرگمی‌های آینده را حذف می‌کند.

سومین ابزار، بازبینی کد است؛ بهترین جا برای اصلاح اسم‌ها قبل از جاافتادن آن‌ها. در راهنمای بازبینی کد روش مشخصی برای گفتن این بازخوردها هست: به‌جای «این اسم بد است» بگویید «این اسم را من گمراه‌کننده می‌دانم چون …». بعد از چند ماه، الگوهای اسم‌گذاری تیم مثل لهجهٔ مشترک می‌شود و اعضای جدید در اولین هفته به آن عادت می‌کنند.

تمرین ده‌روزه برای اسم‌های بهتر

این تمرین ساده را ده روز اجرا کنید: هر روز یکی از کدهای قدیمی خودتان (حتی یک تمرین دو‌ماه پیش) را باز کنید و فقط اسم‌ها را بهبود بدهید؛ نه منطق، نه ساختار، فقط اسم‌ها. می‌بینید که بعضی جاها مجبورید اول فکر کنید «این واقعاً چه می‌کند؟» و همین فکر کردن، ماهیچهٔ اسم‌گذاری را می‌سازد. روز دهم، متوجه می‌شوید کد تازه‌تان هم از همان اول اسم‌های بهتری می‌گیرد.

اسم‌گذاری هنر کوچکی است که با تمرین، به عادت تبدیل می‌شود و بازده آن، سال‌ها با شما می‌ماند. قانون آخر را هم فراموش نکنید: اسم خوب، بهترین کامنتی است که هرگز پاک نمی‌شود؛ قبل از نوشتن کامنت بعدی، یک بار امتحان کنید که آیا می‌شود به‌جایش اسم بهتری انتخاب کرد.