Faragiri

همهٔ زبان‌ها

آموزش نام‌گذاری در کدکد تمیز نوشتن

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

۴بخش
۳دقیقه خواندن
۴عمق

چهار نام، یک مقدار

هر نام چند پرسش را حذف می‌کند و چند تا را باقی می‌گذارد

فاصله میان دو سر هر ردیف همان چیزی است که آن نام برای خواننده انجام می‌دهد.

تعداد پرسشی که خواننده پس از دیدن نام هنوز دارد، از سه تا صفر

پرسش‌های باقی‌ماندهپرسش‌های حذف‌شده

  1. n۳۰چه چیزی، بر چه واحدی، و از کجا آمده: هیچ‌کدام جواب ندارند
  2. nerkh۲۱می‌گوید نرخ است و نمی‌گوید نرخ چه چیزی و بر چه واحدی
  3. nerkh_har_kilo۰۳هر سه پرسش را جواب می‌دهد و همان‌جا می‌ایستد
  4. نام بسیار بلند۰۳همان سه پرسش، با کلمه‌هایی که هیچ پرسش تازه‌ای حذف نمی‌کنند

دو ردیف آخر یک عدد دارند و یکسان نیستند. این نمودار طول را نمی‌شمارد، و همان است که تفاوتشان را نشان نمی‌دهد.

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

سه نام برای یک مقدار، در یک تابع محاسبه کرایه:

  • n چیزی نمی‌گوید و خواننده باید تعریفش را پیدا کند
  • nerkh می‌گوید نرخ است و نمی‌گوید نرخ چه چیزی و بر چه واحدی
  • nerkh_har_kilo هر دو پرسش را جواب می‌دهد و تمام
  • nerkh_har_kilo_be_rial_baraye_bare_adi پرسش تازه‌ای جواب نمی‌دهد و فقط سطر را می‌شکند

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

چیزی که در نام نباید باشد

نوع در نام نباشد. list_e_sefaresh اطلاعاتی می‌دهد که ویرایشگر همین حالا نشان می‌دهد و روزی که ساختار داده عوض شود دروغ می‌شود، و کسی هم نام را عوض نمی‌کند. همین‌طور پیشوند کلاس روی هر صفت، که فقط تکرار است.

مخفف هم نباشد، مگر آنکه در همان حوزه استاندارد باشد. mbl برای مبلغ، یک بار برای نویسنده صرفه‌جویی می‌کند و صد بار برای خواننده هزینه دارد. استثناها واقعی‌اند: هر خواننده کد id و url را می‌شناسد و باز کردنشان کد را بدتر می‌کند.

نام بولین و نام تابع

یک بولین باید مثل یک ادعا خوانده شود که جوابش بله یا خیر است: pardakht_shode و نه vaziat. و نامش مثبت باشد، چون not gheyre_faal دو بار نفی است و هر خواننده یک بار غلط می‌خواندش.

نام تابع فعل است و می‌گوید چه می‌کند نه چطور. kerayeh_hesab_kon درست است و halgheh_roye_bar غلط، چون روش را در نام قفل می‌کند و اولین بازآرایی نام را دروغ می‌کند. اگر نام تابع کلمه «و» دارد، آن تابع دو کار می‌کند و عوض کردن شکل، بدون عوض کردن رفتار جای بعدی است.

جایی که کار گیر می‌کند، فارسی نوشتن با حروف لاتین است

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

ابزار، و سالی که این حرف درست است

در سال ۲۰۲۶، تغییر نام در سراسر پروژه کار ویرایشگر است و نه کار جست‌وجو و جایگزینی: در VS Code همان میان‌بر تغییر نام، فقط همان نماد را عوض می‌کند و رشته‌های هم‌املا را دست نمی‌زند. جای sed روی کل مخزن را گرفته، که رشته‌های داخل متن و نام‌های مشابه در ماژول‌های دیگر را هم عوض می‌کرد. برای اینکه سبک نام‌ها یکدست بماند، ruff قاعده‌های نام‌گذاری را بررسی می‌کند و رایگان است.

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

کنار این

بالای این