کامنت ها را با کد های بهتری جایگزین کنید

در این مطلب در رابطه با نحوه استفاده کاربردی و صحیح کامنت و کد صحبت خواهیم کرد؛امیدوارم مورد استفادتون قرار بگیره.

توسعه نرم‌افزار امری ذاتا مشترک است. اگر فارغ از بزرگی در یک شرکت کار می‌کنید، بدیهی است که با دیگران به صورت تیمی مشغول هستید.

من به کامنت گذاری به عنوان راهنمایی برای توابع خاص یا کلاس‌ها اعتقاد دارم، زیرا آن‌ها می‌توانند به دو طریق به توسعه دهندگان کمک کنند:

• با استفاده از کامنت‌ها به کُد بروید تا رفتار IDE را هدایت کنید.
• برای جلوگیری از سوءتفاهم در مورد چگونگی طراحی بلاک کد (افزایش عملکرد، رفع اشکال و ...) اطلاعات متنی بیشتری اضافه کنید.

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

<?php

public function calc() 
 {
  // Add b to a 
  $c =  $this->a +  $this->b;

  // return the result of a + b 
  return  $c;
}

این موارد بالا می‌تواند نتیجه مشورتی باشد که به تیم پیشنهاد می‌شود تا کامنت‌های خود را به کد اضافه کنند.

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

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

ما حتی می‌توانیم بدون نوشتن یک خط کامنت، بیان دقیق‌تری راجع به نام کلاس‌ها، توابع و متغیرها داشته باشیم.

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

<?php

/**
 * Calculate spending limit by customer income and try to find a room to a lower price.
 */
public function rentRoom($income)
{
    $spending = round(($income*0.15) / 12);
    foreach ($this->rooms as $room) {
        if ($room->price <= $spending) {
            return $room;
        }
    }
    throw new RoomNotFoundException();
}

فقط یک خط کامنت می‌تواند قابل قبول باشد. یا می‌توانیم کد را بازبینی کنیم تا واضح‌تر ماژولار شود و از هرگونه اظهار نظر جلوگیری شود؟

<?php

/**
 * Rent a room based on customer's income
 * 
 * @params integer $income
 */
public function rentRoom($income)
{
    try {
        $this->findRoomByPriceLimit(
            $this->calculateCustomerSpending($income)
        );
    } catch (\Eception $exception) {
        // do something with error
    }
}


public function findRoomByPriceLimit($limit) 
{
    foreach ($this->rooms as $room) {
        if ($room->price <= $limit) {
            return $room;
        }
    }
    throw new RoomNotFoundException();
}


public function calculateCustomerSpending($income, $percentage = 15)
{
    return round(
        ($income*($percentage/100)) / 12
    );
}

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

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

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

جمع بندی

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

در IDE مدرن (مانند PHPStorm یا VSCode) کامنت‌ها اغلب برای بهبود پیمایش کد مفید هستند.

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

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

منبع