کامنت نویسی در PHP

یکی از اصلی ترین تفاوت های بین برنامه نویس های خوب با بقیه برنامه نویس ها، توانایی نوشتن Code Comment های مناسب است.

Code Comment چیست؟

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

در PHP ما دو مدل کامنت نویسی می توانیم داشته باشیم: 1- کامنت های تک خطی و 2- کامنت های چند خطی

کامنت تک خطی:

کامنت نویسی به صورت تک خطی، به دو روش در PHP قابل انجام است. که در تکه کد زیر می توانید مشاهده کنید.

<?php
#Code Comment First Type
echo "SokanAcademy.com - PHP Course - Comment Section" //Code Commend Second Type
?>

کامنت نویسی چند خطی:

بعضی از مواقع نیاز می شود برای یک تکه کد، از چند خط کامنت استفاده شود.

<?php
/* 
Code Comment First Line
Code Comment Second Line
.
.
.
*/
echo "SokanAcademy.com - PHP Course - Comment Section"
?>

💎 نکته هایی برای حرفه ای تر شدن

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

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

• ثبت کارهایی که باید در آن بخش انجام شود. در اصطلاح دنیای برنامه نویسی به این کامنت ها، کامنتهای ToDo گفته می شود که در ابتدای متن کامنت، عبارت ToDo را قرار می دهید و بعد توضیح می دهید چه کارهایی در آن بخش از برنامه نیاز است انجام شود. برنامه هایی وجود دارد که می توانند کدهای برنامه ی شما را بگردند تا لیستی از ToDo هایی که نوشته اید را برایتان نمایش دهند. این کامنت ها در کارهای تیمی، برای هماهنگی بین اعضای تیم می تواند مفید باشد. از دیگر موارد استفاده از این کامنت می توان به زمان هایی اشاره کرد که به دلیل کمبود زمان یا MVP بودم محصولی که کدش را می نویسید Technical Debts یا بدهی های فنی ایجاد می شود، با ToDo کردن آنها می توانید بعدا به سراغ شان بیایید.

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

// TODO MdM Should probably use a StreamedResponse

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

//  Created by Hamid Reza Madani on 01/08/2022.
//  Copyright © 2022 Company. All rights reserved.

• ارائه ی اطلاعات اضافه درباره ی علت نوشتن یک کد و یا منطقی که شما را به آن کد رسانده است. به عنوان یک مثال ساده فرض کنید برای ثبت تاریخ، ما راه های زیادی داریم ولی مدیرتان به شما گفته است که تاریخ را به صورت dd-mm-yy ثبت کنید. برای اینکه بعدا برایتان سوال نشود که چرا تاریخ را با فرمتی دیگر ثبت نکرده اید، می توانید بالای آن یک کامنت بنویسید که از شما این الگو خواسته شده است.
• تولید مستندات فنی به صورت خودکار هم یکی دیگر از کامنت هایی است که ما در برنامه می نویسیم .برنامه هایی وجود دارد که می تواند به صورت خودکار از روی کدهای شما، مستندات فنی را تولید کند. این برنامه ها از شما می خواهند که به صورتی خاص در کدتان کامنت هایی بنویسید.