مقدمه ای بر دستورالعمل های نام گذاری: نوشتن نام های معنی دار متغیر

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

فواید معنی دار کردن نام ها

چند نفر از ما با پیدا کردن یک نام منحصر به فرد برای یک متغیر یا تابع خاص متوقف شده و شگفت زده شده ایم؟ یک مهندس معروف روزی گفت:

فقط دو چیز سخت در علوم کامپیوتر وجود دارد: نامعتبر کردن حافظه پنهان و نامگذاری چیزها

اما چرا نامگذاری درست چیزها بسیار مهم است؟

این احتمال وجود دارد که وقتی افکاری مانند “این نام اصلاً به چه معناست؟”، “تفاوت بین این و آن چیست؟” یا “این واقعاً چه کاری انجام می دهد؟” را می دانید. تعداد کمی از ما ارزش داشتن نام های عمدی را می دانیم. وزن آن به آینده منتقل می شود. می تواند بر شما و تیم شما تأثیر منفی بگذارد. در غیر این صورت، اثر معکوس منجر به بهبود در زمینه های زیر می شود:

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

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

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

هیچ دستورالعمل یا فکر قبلی در نامگذاری شما را از اتمام پروژه یا کار باز نمی دارد.

شما اجرای کد را دوباره بخوانید تا بفهمید چه اتفاقی در حال رخ دادن است. زمان بیشتر از آنچه لازم است می گذرد. به نظر می رسد که عدم صرف زمان برای نامگذاری صحیح نرم افزار در دراز مدت دو برابر می شود.

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

کیت شروع برای دستورالعمل‌های نام‌گذاری (و بهترین روش‌ها)

برای مدل‌سازی یک دستورالعمل نام‌گذاری، باید بدانیم نام‌ها چگونه طراحی می‌شوند. این امر مستلزم انبوهی از تجربه در برنامه نویسی است، مخصوصاً با یک تیم.

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

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

در اینجا نکات اولیه من در مورد Clean Code و مقالات دیگر وجود دارد که نکات بسیار خوبی را برای دنبال کردن ارائه می دهد.

از نام های آشکار کننده قصد استفاده کنید

به سؤالات بزرگ برای متغیر، تابع یا کلاس فکر کنید. به سؤالات زیر پاسخ دهید: «چرا وجود دارد»، «چه کار می کند» و «چگونه از آن استفاده می شود».

وقتی هدف واقعی آن را پیدا کردید، نام ها را دوباره تغییر دهید

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

از اطلاعات نادرست و نادرست پرهیز کنید

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

• مخفف می تواند نادرست باشد.

به طور کلی اختصار ممنوع است.
به عنوان مثال c می تواند مخفف «کربن»، «سلسیوس» یا «قرن» باشد.

نام هایی که با مفاهیم برنامه نویسی موجود در هم آمیخته می شوند گیج کننده هستند.

به عنوان مثال str می تواند به معنای “قدرت” یا در اصطلاح برنامه نویسی “رشته” باشد. در محدوده پروژه های مختلف متفاوت خواهد بود، اما زمانی که در حال ساخت یک بازی RPG هستید ممکن است دچار این تضاد شوید.

با این حال، من یک استثنا برای لیستی که حلقه می شود، قائل می شوم.

به عنوان مثال cards یک آرایه است و من فقط یک آیتم را انتظار دارم.

cards.map((c) => c);

c می تواند به عنوان کارت بازنویسی شود، اما قبلاً اشاره شده است.

• صفر 0، حروف کوچک o، حروف بزرگ O، و حروف کوچک l واقعاً نام متغیرهای وحشتناکی هستند.

تشخیص تفاوت بین عدد صفر، حرف “o”، بزرگ و کوچک دشوار است. در مورد حرف کوچک “ل” و عدد هم همینطور است 1. وقتی با هم ترکیب شوند بیشتر!

به عنوان مثال

let a = l;  
if ( O == l )  {
  a = O1;
} else {
  l = 01;
}

• نامگذاری سری اعداد غیر اطلاعاتی است.

ممکن است آنها به صورت هیروگلیف نیز نوشته شوند.

به عنوان مثال

Array.prototype.swap = function (x1, x2) {
  var b = this[x1];
  this[x1] = this[x2];
  this[x2] = b;
  return this;
}

x1 می توانست باشد source و x2 می توانست باشد target.

تمایز معنادار ایجاد کنید

هنگامی که با مفاهیم مشابهی روبرو می شوید، که اغلب نامی بسیار کلی به آن داده می شود، ممکن است وسوسه شوید که از آن در هر جای دیگری با یک نسخه کمی بهینه سازی شده استفاده کنید. اما شما نمی توانید (و این فقط نامگذاری تنبل است).

هنگامی که به موارد زیر برخورد کردید، تمایزات بیشتری ایجاد کنید:

• ختم جمع با «s»

به عنوان مثال جمع apple فقط یک حرف متفاوت است apples. با چشمان آموزش ندیده، برنامه نویسان می توانند این جزئیات حاشیه ای را از دست بدهند. آنها را می توان با تبدیل آنها به اسم های جمعی حل کرد. به چیزی شبیه به آن فکر کنید basketOfApples یا bunchOfApples.

• کلمات پر سر و صدا – معنی یکسان، املای متفاوت

حتی از یک اصطلاح برای دو هدف متفاوت استفاده نکنید.

به عنوان مثال تفاوت بین چیست؟ totalOfCash و amountOfIncome? هر دوی آنها به یک معنا هستند. ویژگی را دریابید و متمایز کنید.

کلمات سر و صدا نامشخص

به عنوان مثال پیوست کردن کلماتی مانند این مقالات مانند a، an، یا the هنگامی که شما به سادگی نام آن را می نویسید، معنای متفاوت تری ندارید. استفاده از آنها اشکالی ندارد. فقط در موردی مانند آن بی فایده است thePerson یا aPerson. نام ها را بیش از یک یا دو حرف متفاوت کنید.

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

function sendEmail(input) {
 const a_txt;
 setMessage(a_txt + input)
}
_________________________________________________ 
function sendEmail(input) {
 const text;
 setMessage(text + input)
}

یک نسخه کوتاه تر از کلمات نویز زمانی است که هیچ کلمه دیگری برای توصیف بیشتر آنها وجود ندارد. پسندیدن total و amount هنوز هم مشابه هستند و به یک معنی مشترک هستند، به جز اینکه به تنهایی چیز زیادی نمی گوید. “کل” از چه چیزی؟ “مقدار” چه چیزی؟

از نام های قابل تلفظ استفاده کنید

وقتی وارد حوزه فناوری می شوید، تعجب خواهید کرد که برنامه نویسی یک فعالیت اجتماعی است. بنابراین اگر نمی توانید متغیری را که به آن اشاره می کنید تلفظ کنید، بدون احمقانه به نظر رسیدن نمی توانید بحثی داشته باشید!

از نام های قابل جستجو استفاده کنید

نوار جستجو در ویرایشگر کد شما می تواند نتایج را زمانی که نام ها منحصر به فرد تر می شوند محدود کند. این زمانی ضروری است که وظیفه بازسازی پایگاه کد را بر عهده داریم.

در اینجا نحوه جستجوی اسامی بیشتر آمده است:

از نام های طولانی تر به نام های کوتاه تر استفاده کنید
اسامی تک حرفی باعث ایجاد حداکثر ابهام می شود. نام های طولانی تر به عنوان یک شناسه بهتر عمل می کنند و زمینه کافی را ارائه می دهند.

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

از قرارداد نامگذاری ثابت بر روی مقادیر خام استفاده کنید
به عنوان مثال MAX_PASSENGER_ON_BOARD بیشتر از عدد 9 را به شما می گوید.

نام کلاس ها

در اینجا چند دستورالعمل کلاسیک برای کمک به نام‌گذاری کلاس‌هایی که در زبان‌های شی گرا وجود دارند، آورده شده است.

• اسم یا اسم عبارت

با استفاده از یک اسم، معنی را درک می کنید new کلمه کلیدی که آن را مقداردهی اولیه می کند.

به عنوان مثال

const apple = new Fruit("sweet", "crunchy");

با فعل متصل به آن یا به صورت فعل کمتر معنا پیدا می کند. به عنوان مثال new createFruit()، new Swim().

به کلمات ملموس بیندیشید، چیزی که یک معنی واضح دارد.

هنگام فراخوانی متدی که حالت را تغییر می دهد، از نام کلاس هایی که با وضعیت ناسازگار هستند، اجتناب کنید.

نام را کمتر مشخص کنید.

به عنوان مثال new FelineDomesticAnimal از آنچه که می تواند یا نمی تواند باشد بسیار دور است (می گوید فقط گربه ها مجاز هستند). چیزی مثل new Animal اجازه می دهد تا تنوع بیشتری داشته باشد.

تمام مقادیر مورد انتظار را پوشش دهد. ابزار رسیدن به هدف را ننویسید. از تناقض بپرهیزید. فیلد را بنویسید. از نامی استفاده کنید که برای مقادیری که حالت ممکن است داشته باشد اعمال شود.

به عنوان مثال یک کلاس با متد start و end ممکن است نامی مانند Race، نه FinalRace. “نهایی” نشان می دهد که با روش طرف است end.

آن را فراگیر کنید.

نام روش ها

نام روش باید یک فعل یا یک نام عبارت فعل باشد.

به عنوان مثال saveDocument، playMusic یا delete.

برای دسترسی‌ها، جهش‌دهنده‌ها و محمول‌ها، کنوانسیون نام‌گذاری JavaBeans می‌گوید که باید برای مقدارشان نام‌گذاری شوند و پیشوند با get و set. بنابراین، فقط برای دسترسی میدانی از آنها استفاده کنید.

به عنوان مثال

const grade = student.grade();
teacher.setGrade(80);

برای روش هایی که عوارض جانبی دارند، از آن استفاده نکنید get، is، یا has پیشوندها

از نام های دامنه راه حل استفاده کنید

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

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

اضافه کردن زمینه معنی دار

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

نتایجی که اظهار شده

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

منابع