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

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

• توضیح بخش‌هایی از کد که درک آنها نیاز به اطلاعات بیشتری دارد
• غیرفعال کردن بخشی از کد در فرایند دیباگینگ
• ارائهٔ نکاتی برای خود دولوپر که پس از مراجعه به سورس‌کد در آینده، متوجهٔ نحوهٔ کدنویسی خود گردد!
• ارائهٔ توضیحاتی در مورد دولوپر، فریمورک‌های استفاده شده، سالی که اپلیکیشن توسعه یافته و غیره

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

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

<!-- Comment goes here. -->

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

به طور کلی، کامنت‌ها در زبان PHP هرگز برای مرورگر ارسال نمی‌شوند (حتی اگر به سورس صفحات مراجعه کنیم). سه نوع کامنت‌گذاری مختلف داریم که نوع اول با # شروع می‌شود که اصطلاحاً Hash Tag یا Pound Sign نامیده می‌شود:

# This is a comment.

به سبک کامنت‌گذاری بالا، اصطلاحاً Sell Style گفته می‌شود چرا که برگرفته از سبک کامنت‌نویسی در شِل لینوکس است. نوع دوم بااستفاده از دو علامت Slash و به صورت // صورت می‌گیرد که اصطلاحاً به آن C Style گفته می‌شود: 

// This is also a comment.

نوع سوم هم که اصطلاحاً Multiline نامیده می‌شود، برای شروع از علائم */ و برای پایان هم /* استفاده می‌شود:

/* 
This is a longer 
comment that spans 
three lines. 
*/

به منظور روشن‌تر شدن نحوهٔ استفادهٔ عملی از کامنت‌گذاری در PHP،‌ اسکریپت زیر را در نظر بگیرید:

<?php
/*
This is A PHP Course
Authored by Behzad Moradi
Published by SokanAcademy.com
*/

// This is the 1st echo
echo "This tutorial is about commenting in PHP <br>"; /* This shows how to use C Style commenting at the end of a line */
echo "We have 3 different commenting styles in PHP"; # This is the 2nd echo
# This is the end of the script

همان‌طور که مشاهده می‌شود، در ابتدای اسکریپت از خط ۲ام تا ۶ام از سَبک کامنت‌نویسی چندخطی (Multiline) استفاده کرده‌ایم. سپس در خط ۸ام با استفاده از علائم // یک خط از کد را کامنت‌ کرده‌ایم و می‌بینیم که به چه شکل در انتهای خط ۹ام هم با استفاده از علائم */ و /* که مخصوص کامنت‌نویسی چندخطی است، در یک خط استفاده کرده‌ایم. در خط ۱۰ام هم از علامت هَشتگ برای کامنت‌ کردن انتهای خط استفاده کرده‌ایم و در نهایت هم در خط ۱۱ام مجدد از هَشتگ اما این بار برای کامنت کردن یک خط مجزا استفاده کرده‌ایم (در واقع، از جایی که این علائم قرار می‌گیرند تا انتهای همان خط، از دید مفسر پنهان خواهد ماند).

نکاتی مهم در مورد کامنت‌نویسی

به طور کلی، اگر به سورس‌کد پروژه‌های حرفه‌ای در گیت‌هاب، فریمورک‌ها و لایبرری‌های معروف و اساساً به نحوهٔ کدنویسی دولوپرهای حرفه‌ای نگاه کنیم، خواهیم دید که ایشان به بهترین شکل ممکن اقدام به کامنت‌نویسی می‌کنند. در اینجا منظور از بهترین، این است که یکسری Best Practice در حین کامنت‌نویسی می‌بایست همواره مد نظر قرار گیرد که برخی از مهم‌ترین آنها عبارتند از:

عدم نوشتن کامنت برای بدیهیات

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

// This variable stores user name
$username = null;

مسلماً اگر نحوهٔ نامگذاری متغیرها -که در آموزش‌های آتی به تفصیل در مورد آنها صحبت خواهیم کرد- درست صورت گیرد، نام متغیر گویای ماهیت‌اش خواهد بود و اصلاً نیازی به نوشتن کامنت نخواهیم داشت.

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

بسیاری از دولوپرها را می‌بینیم که به درستی کامنت‌نویسی می‌کنند اما وقتی که سورس‌کد را ریفکتور می‌کنند (تغییر می‌دهند)، فراموش می‌کنند تا کامنت‌ها را نیز آپدیت کنند و همین مسئله منجر به این خواهد گشت تا در آینده، هم خود دولوپر و هم دیگر همکارانش دچار سردرگمی شوند. به عنوان مثال داریم:

// This variable stores user name
$username = $firstname . $lastname;

همان‌طور که ملاحظه می‌گردد، کامنت این پیام را به ما می‌رساند که متغیر username$ حاوی نام کاربر است اما این در حالی است که می‌بینیم این متغیر حاوی دو متغیر دیگر است تحت عناوین firstname$ و lastname$ که به ترتیب به معنی «نام» و «نام‌خانوادگی» می‌باشند. چنین تناقضاتی منجر به سردرگمی دولوپرها در آینده خواهد شد و تا حد ممکن می‌بایست از آنها اجتناب کرد.

کد بایستی گویا باشد

وقتی ما کدنویسی می‌کنیم، می‌بایست تمام تلاش خود را به کار بندیم تا کد ما اصطلاحاً Self-explanatory باشد؛ به عبارت دیگر، سورس‌کد،‌ فاصله‌گذاری، نام‌گذاری متغیرها/کلاس‌ها/متدها و غیره می‌بایست آن‌قدر گویا باشند که ما به عنوان یک دولوپر نیاز به حداقل کامنت‌نویسی داشته باشم. به عنوان مثال داریم:

public function showUserInfo ($firstname = null, $lastname = null) {
    return $firstname . $lastname;
}

همان‌طور که ملاحظه می‌شود، در اسکریپت فوق فانکشن یا تابعی داریم تحت عنوان ()showUserInfo که این وظیفه را دارا است تا دو پارامتر ورودی گرفته، سپس آنها را اصطلاحاً Concatenate کند (به‌ هم بچسباند) سپس نتیجه را بازگرداند (در آموزش‌های آتی به تفصیل در مورد فانکشن‌ها توضیح خواهیم داد).

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