احسان رضایی

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

- مفهوم.

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

1) از نام های دقیق استفاده کنید.

 اگر کسی بدون کامنت های شما نمیتونه ایده و هدف شما رو بفهمه اصلا خوب نیست. بدترین حالت زمانی هست که نام به کسی که اون رو میخونه دروغ بگه!

2) اجتناب از نام های بی معنی.

نام هایی مثل i,j,k و... تنها زمانی قابل قبول هستن که در یک حلقه استفاده بشن. در باقی موارد خوانایی رو سخت میکنن.

معمولا توی کتاب های علوم کامپیوتر از این روش برای تعریف یک فرمول(با استفاده از شبه کد به منظور سریعتر نوشتن) استفاده میشه در صورتی که اگر پاراگراف بالای اون فرمول رو مطالعه نکنید چیزی ازش نخواهید فهمید.

3) نام کلاس ها، اینترفیس و پراپرتی ها.

نام کلاس میتونه شامل یک یا چند اسم باشه. از فعل(تنها) نباید استفاده کرد. “data”, “manager”, “info”, “processor”, “handler”, “maker”, “util” و موارد مشابه به علت مبهم بودنشون اجتناب کنید.

Interface ها معمولا اسم یا صفت هستن. میتونید از پیشوند (مثلا Interface) هم استفاده کنید.

namespace Psr\Log;

/**
 * Describes a logger instance
 */
interface LoggerInterface
{

property ها اسم یا صفت هستن. برای پراپرتی هایی با مقدار دودویی(0 یا 1) میشه از پسوند هایی مثل “Is”, “Can”یا “Has” در جاهای مناسب استفاده کرد.

نام Method باید شامل یک یا چند فعل باشه و کاری که انجام میده رو توضیح بده. نه اینکه چطور اون کار رو انجام میده.

ضروری نیست اما بهتره یک کلاس مشتق پسوند کلاس والد رو به همراه خودش داشته باشه.

class Exception {}

class InvalidArgumentException extends Exception {}

- پایداری

از یک نام تنها برای یک مفهوم استفاده کنید. 

مثال خوبتر این مورد استفاده از begin/end هست و اگر ازشون به عنوان شروع یا پایان استفاده کردین. کنارش از start/finish به صورت ترکیبی استفاده نکنید!

1) دستورالعمل های سبک و چهارچوب کدنویسی رو دنبال کنید.

هنگام توسعه ی پروژه، تیم باید در مورد سبک نوشتن کد و قاعده و قانون های مرتبط با کدنویسی توافق کنه. و همه ملزم به رعایتش بشن. در PHP رایج ترین قرارداد PSR-2 هست و اکثر پروژه ها بر اساس اون عمل میکنن.

 - کامل نویسی

1) اجتناب از استفاده مجدد نام ها

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

2) اجتناب از خلاصه کردن.

هرگز نام ها رو خلاصه نکنید مثل cnt, iter, amnt, impl و... . مثال:

function cntBigWrds($data, $length)
{
    $i = 0;
    foreach ($data as $iter) {
        if (mb_strlen($iter) > $length) {
            $i++;
        }
    }
    return $i;
}

$data = ['I', 'am', 'word'];
echo cntBigWrds($data, 3);

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

function countWordsLongerThan(array $words, int $minimumLength)
{
    $count = 0;
    foreach ($words as $word) {
        if (mb_strlen($word) > $minimumLength) {
            $count++;
        }
    }
    return $count;
}

$words = ['I', 'am', 'word'];
echo countWordsLongerThan($words, 3);

توجه داشته باشید نام بدون خلاصه نویسی باید کوتاه باشه. در نتیجه زیاده روی نکنید. چیزی مثل ()processTextReplacingMoreThanASingleSpaceWithASingleSpace مطلوب نیست. اگر نام بیش از حد طولانی شده به این معنی هست که میتونید کوتاه ترش کنید.

3) اجتناب از کلمت اختصاری

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

- خوانایی

کد باید به راحتی قابل خواندن باشه. میتونید نام ها رو از داخل مقالات یا کتاب ها انتخاب و استفاده کنید. به عنوان مثال یک پراپرتی به نام TotalAmount به مراتب خوانا تر از AmountTotal هست.

1) دامنه لغات

باید از نام های مورد استفاده در مدل کسب و کار داخل کد استفاده بشه. به عنوان مثال، اگر در پروژه گردشگری از venue به عنوان نام کافه، هتل ها یا جاذبه های توریستی استفاده میکنن ایده ی بدی هست که داخل سورس به جاش از place استفاده کنید. چون شما و کاربران از دو لغت متفاوت استفاده میکنید و این کارتون رو پیچیده خواهد کرد.

2) از نام های انگلیسی استفاده کنید.

اکثر زبان های برنامه نویسی از زبان انگلیسی برای نامگذاری استفاده میکنن و بهتره شما هم همین کارو انجام بدین.