کامنتنویسی در گویش اپلیکیشننویسی PHP
کامنتنویسی یکیاز مهارتهای اصلی برای هر اپلیکیشننویس میباشد. کامنتها طراحی سایت اختصاصی به اپنویسان یاری مینمایند تا کدهای خویش را مستندسازی نمایند، شعور کدها را برای دیگرافراد (و خودشان در آتی) سهل وآسانخیس نمایند و از تولید مشکلات پرهیز نمایند. دراین نوشتهعلمی از سایت راکت به نظارت اصول و شایسته ترین طرزهای کامنتنویسی در لهجه نرم افزارنویسی PHP میپردازیم.
عنایت کامنتنویسی
کامنتنویسی در اپنویسی از التفات بالایی برخورداراست چون به بسطدهندگان قابلیت میدهد کد خویش را به طوری مستندسازی نمایند که شعور آن برای سایر افراد و حتی خودشان در آتی بی آلایشخیس باشد. کامنتها توضیحات مازاد ارائه میدهند که مقصود و همت نصیبهای متفاوت کد را پرنور میسازد. این توضیحات میتوانند به پرهیز از سوءتفاهمها یاری کرده و روند رفع انواع را تسهیل نمایند. همینطور، در پروژههای تیمی، کامنتها ابزار مهمی برای رابطه در میان اعضای مجموعه می باشند. آنها میتوانند قضیهای برای تصمیمگیریهای پیاده سازی و منطق پشت گزینشهای کدنویسی را آماده نمایند. در کل، کامنتها به حفظ و بهبود کد یاری مینمایند و منجر می شوند کد پایداری و قابل شعورتری داشته باشد.
در سود کامنتنویسی میتواند در مسئلههای پایین به ما یاری دهد:
ارتقا خوانایی کد: کامنتها به توضیح تلاش کد و قسمتهای متفاوت آن امداد مینمایند، به این ترتیب دیگر افراد به راحتی میتوانند کد شمارا بفهمند.
مستندسازی کد: کامنتها تحت عنوان مستندات کد کار مینمایند و توضیح میدهند که چرا و چه طور یک قسمت از کد مندرج میباشد.
کاهش احتمال خطاها: با توضیح دادن جزئیات کد، احتمال ساختوساز خطاها کمتر می شود چون نیت و غرض کد بدیهیخیس میباشد.
گونه های کامنتها در PHP
کامنتهای تکخطی: از // یا این که # برای تایپ کردن کامنتهای تکخطی به کار گیری میشود.
// This is a one line comment
# this is also another one line comment
کامنتهای چندخطی: از /* ... */ برای تایپ کردن کامنتهای چندخطی به کار گیری میگردد.
/*
this is a multi-line comment
using slash and asterisk
*/
کامنتهای PHPDoc: این نوع کامنتها برای مستندسازی توابع، متدها و کلاسها به کارگیری میگردد.
/**
* this is a PHPDoc comment
*
* @param int $number parameter details
* @return int return value details
*/
function add($number) {
return $number + 1;
}
مهمترین نکات برای کامنتنویسی
کوتاه و بدیهی بودن: کامنتها بایستی کوتاه و به نقطه باشند. از توضیحات مازاد دوری کنید.
بهروز نگه داشتن کامنتها: هرگاه کد تغییرو تحول مینماید، کامنتها نیز می بایست بهروز شوند تا هماهنگی در میان کد و کامنتها محافظت خواهد شد.
تمرکز بر چراها: بیشتر توضیح دهید که چرا یک کد درج شده میباشد تا اینکه تنها بگویید کد چه کاری اعمال میدهد.
به کارگیری از PHPDoc برای مستندسازی: به کار گیری از کامنتهای PHPDoc برای توابع، متدها و کلاسها به مستندسازی ظریف و جامع کد یاری مینماید.
دوری از کامنتهای هویدا: از تایپ کردن کامنتهایی که بدیهی و مبرهن می باشند دوری کنید.
$i++; // add one value to i
دو نمونه عملی از طریق کامنتنویسی در PHP
به دنبال یک نمونه مطلوب از طریق کامنتنویسی در PHP را مطرح کردهایم که ولی بهاستدلال بی آلایشسازی مقاله از کامنتهای کوتاه استعمال کردهایم.

به کار گیری از رپورتاژ اطلاع رسانی و نشر در کانالهای اجتماعی