رتبه موضوع:
  • 0 رای - 0 میانگین
  • 1
  • 2
  • 3
  • 4
  • 5
راهنمای کامنت گذاری در زبان های کامپیوتری
#1
تمامی توسعه دهندگان و برنامه نویس هایی که روی پروژه های بزرگ کار کرده اند، از اهمیت کامنت (توضیح = comment) گذاری هنگام کدنویسی واقف هستند. زمانی که روی یک اپلیکشن کار می کنید، به مرور با افزایش امکانات، پیچیدگی آن نیز افزایش می یابد. ممکن است در کد بارها و بارها به فانکشن ها یا متغیرهای خاصی ارجاع داده شود و از آنها اطلاعات یا مقادیر خاصی گرفته شود. آیا می دانید، اگر پس از مدتی به کد مراجعه کنید، چیز زیادی از چگونگی کارکرد آن به خاطر نخواهید داشت؟ آیا می دانید که مجبورید ساعت ها صرف کنید تا به یاد بیاورید هر کدام از قسمت های کد چه کار می کند؟ شاید تعجب کنید اما این یک واقعیت است.

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

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

توضیح: فانکشن، مجموعه ای کد در یک برنامه کامپیوتری است که وظیفه خاصی را انجام می دهد.

توضیح: در این متون به شدت سعی شده تا توضیحات و مثال ها به زبان کاملا ساده آورده شوند. به همین دلیل ممکن است بعضی از آنها کاملا دقیق و درست نباشند.

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

استایل های کامنت ها: یادآوری

توجه کنید که این الگوها با این توضیحات کامل، به ندرت در یک گایدلاین (راهنمای مرجع = guidelines) آورده می شوند. معمولا هیچ یک از زبان های برنامه نویسی راجع به روش های کامنت گذاری توضیحی نمی دهند. زیرا هر گروهی از دولوپرها سیستم کامنت گذاری مخصوص به خودش را اختراع و استفاده می کند.

کامنت های این لاین

معمولا هر زبان برنامه نویسی ای توصیه به استفاده از کامنت های این لاین (inline) دارد. آنها محدود به یک خط هستند. مثلا در زبان های C, C++, javascript و PHP سیستم کامنت گذاری تک خطی به صورت زیر است:

// begin variable listing
var myvar = 1;
..

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

هنگام توضیح عباراتی که دارای علامت «}» (آکولاد) هستند نیز می توانید از روش زیر استفاده کنید.

if(callAjax($params)) { // successfully run callAjax with user parameters
... code
}

بلاک های توضیح

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

/**
* @desc opens a modal window to display a message
* @param string $msg - the message to be displayed
* @return bool - success or failure
*/
function modalPopup($msg) {
...
}

در بالا یک مثال ساده از کامنت توضیح دهنده یک فانکشن آورده شده. یک فانکشن در زبان جاوااسکریپ با نام modalPopup که یک پارامتر (msg$) در آن قرار می گیرد. در کامنت توضیحی مشابه به آنچه در PHP مرسوم است (PHPDocumentor) نوشته شده. در این روش علامت @ را قبل از هر مشخصه فانکشن می گذاریم و آن مشخصه را توضیح می دهیم. توجه کنید که این کامنت هیچ تاثیری روی عملکرد فانکشن ندارد و شما می توانید به جای desc@ بنویسید description@.

این مشخصه های کوچک (که با علامت @ شروع می شوند) را تگ (برچسب) های کامنت می نامند. که در طراحی سایت ها بسیار مرسوم هستند. پس از آنها با آزادی و فراوانی در کد نویسی استفاده کنید. معمولا برای نوشتن متون مهم نیز از آنها کمک می گیریم. همچنین کامنت گذاری /* … */ را فراموش نکنید. این روش (بدلیل اینکه در دو سمت عبارت کامنت قرار می گیرد) عبارت را بسیار واضح تر از کامنت گذاری با دو اسلش (//) (که فقط در ابتدای متن قرار می گیرد) نشان می دهد.

کامنت های گروهی / کلاسی

به جز فانکشن ها و لوپ ها (loop، مانند for یا foreach)، بلاک های توضیح کاربرد دیگری نیز دارند. یکی از مکان هایی که نیاز است توضیحات کاملی داده شود، بالای کد است. معمولا در بالای هر فایلی از سایت، بلاک توضیحی قرار داده می شود. این توضیحات در بسیاری از CMS ها (سیستم مدیریت محتوا = Content Management System) مانند ورد پرس دیده می شود.

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

/**
* @desc this class will hold functions for user interaction
* examples include user_pass(), user_username(), user_age(), user_regdate()
* @author Jake Rocheleau jakerocheleau@gmail.com

* @required settings.PHP
*/
abstract class myWebClass { }

در اینجا کد تعریف کلاس myWebClass را می بینید. در بالای آن مقداری اطلاعات متا شامل نام و ایمیل نویسنده کد اضافه شده است.

توضیح: اطلاعات متا (meta) در صفحات اینترنتی، وظیفه توضیح کد را دارند. این متون در حالت عادی دیده نمی شوند. بلکه اگر کسی کد سازنده صفحه (source) را نگاه کند، آنها را می بیند. برای دیدن سورس صفحه مثلا در مرورگر کروم باید از سربرگ View گزینه Developer و سپس View Source را بزنید.

یکی از موارد استفاده اطلاعات متا برای گذاشتن اطلاعات تماس دولوپر (developer) است. نوشتن آنها خصوصا زمانی که دولوپرها در حال نوشتن کدهای اوپن سورس هستند بسیار مفید است تا اگر کاربری باگی پیدا کرد از این طریق بتواند به آنها خبر دهد یا کمک بطلبد. این کار در پروژه های بزرگ که افراد مختلفی از یک تیم روی آن کار می کنند، نیز مفید است. (در صورتی که شما جزیی از یک شرکت کامپیوتری هستید و می خواهید در اطلاعات متا، خود را نویسنده کد بنامید، حتما شرکت خود را از این مسئله مطلع کنید.)

در کامنت بالا تگ required@ چیزی است که معمولا در پروژه های بزرگ کاربرد دارد. از این تگ معمولا برای صفحاتی استفاده می شود که باید حتما قبل از کد شما، اینکلود (include) شوند. اضافه کردن این جزییات در پروژه های بزرگ - که ممکن است بخش هایی از کد خودتان را هم فراموش کنید - نقش یک یاداور خوب برای فایل های مورد نیاز دارد.

کامنت گذاری فرانت اند (Front-end Code Commenting)

توضیح: کدهای Front end در وب به بخشی از کد گفته می شود که به مرورگر ارسال می شود و در سورس صفحه می توان آنها را دید. در مقابل آن، کدهای Back end قرار دارد که در سرور آنالیز شده و نتیجه آنها به صورت فرانت اند به مرورگر فرستاده می شود. کامنت هایی که در کد بک اند گذاشته می شوند، در سورس صفحه (source = کد سازنده صفحه وب) دیده نمی شوند.

توضیح: بعضی کدها مانند PHP در سرور بررسی می شوند و جزو کدهای بک اند هستند. نتیجه آنها پس از بررسی، به صورت کدهای فرانت اند به مرورگر فرستاده می شود. HTML، CSS و جاوااسکریپت نمونه هایی از کدهای فرانت اند هستند که توسط مرورگر بررسی و نتیجه به صورت تصویر به کاربر نشان داده می شود.

901015-www-Narenji-ir-Source-Code-Comment-Styling-2.jpg

تاکنون درباره قالب های کامنت گذاری توضیح دادیم (//، /* */ و بلاک کامنت)، حالا کم ریزتر می شویم به صورت اختصاصی به سراغ CSS و جاوااسکریپت می رویم. جاوااسکریپت اجازه کامنت گذاری مشابه زبان های جاوا، PHP، سی و C++ را می دهد. اما CSS فقط از روش اسلش و ستاره (/* */) پشتیبانی می کند. در ادامه کمی راجع به گروه های استایل CSS صحبت می کنیم.

گروه های استایل CSS

آنهایی که سال ها است CSS می نویسند و با آن زندگی می کنند، کم کم شروع به ساخت سیستمی از کامنت گذاری می کنند که برای خودشان کاملا معنی دار است. برای مثال هنگام نوشتن CSS، بلاک های کد مشابه را کنار یکدیگر می گذارند.

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

resets@ : مربوط به کدهایی که مارژین ها، پدینگ ها، فونت ها، رنگ ها و … پیش فرض مرورگر را از بین می برد و صفر می کند. در اینجا می توانید این کدها را پیدا کنید .

@fonts : برای چگونگی نمایش تگ های p، h، لینک ها و …

navigation@ : برای شکل دادن به منوی اصلی سایت

layout@ : برای wrapper, container, sidebars

header & @footer@ : این ها بر حسب نوع طراحی متفاوت هستند. ممکن است شامل استایل های (کدها و دستورات) لینک ها، لیست ها، ستون های footer، header یا زیر منوها باشند.

زمانی که گروه های استایل را می نویسید، استفاده از سیستم تگ گذاری بسیار مفید است. بر خلاف PHP و جاوااسکریپ (که در بالا دیدیم، از علامت @ برای کار دیگری استفاده می شد) در CSS از علامت @ قبل از نام گروه ها استفاده می کنیم. دو مثال در زیر آورده ام:

/** @group footer */
#footer { styles... }


/** @group footer, small fonts, columns, external links **/

شما می توانید علاوه بر تگ گذاری، مقداری اطلاعات نیز در کامنت بگذارید. باید سعی کنید، همه چیز را ساده و سر راست نگه دارید تا CSS به سادگی قابل خواندن باشد. کامنت گذاری به این کار بسیار کمک می کند. کامنت گذاری در واقع نوعی ثبت اسناد و نوشته ها است. پس به محض اینکه سواد یاد گرفتید و توانستید بنویسید، باید همراه آن کامنت گذاری را نیز شروع کنید!

منبع
[عکس: <a href=www.Mojsazan.com.gif]" class="mycode_img" />
پاسخ
سپاس شده توسط
#2
۱. به گونه ای بنویسید که قابل خواندن باشد

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

function getTheMail() {
// code here will build e-mail
/* run code if our custom sendMyMail() function call returns true
find sendMyMail() in /libs/mailer.class.PHP
we check if the user fills in all fields and message is sent! */
if(sendMyMail()) { return true; // keep true and display onscreen success
}
}

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

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

در پروژه هایی که فایل های مختلف داخل یک دیگر اینکلود (include) شده اند و یا از یک فانکشن خارجی (3rd party) استفاده می کنند، کامنت گذاری را فراموش نکنید. این پروژه ها گاهی بی نهایت پیچیده می شوند. پس سعی کنید همیشه کامنتی در بالای هر فایل (حتی اگر از جایی دیگر، برای کاری دیگر دانلود و به پروژه تان اضافه شده) بگذارید، تا با دیدن آن عملکرد کد را به یاد بیاورید.

۲. کمی فضا برای نفس کشیدن

واقعا نمی توانم آن طور که باید از اهمیت و فواید فضای خالی (whitespace) در کد بگویم. خصوصا این فضا برای دولوپرهایی که روی پروژه های بزرگ کار می کنند، حیاتی است. این پروژه ها گاهی حاوی صدها فایل و هر فایل دارای صدها خط کد است. در این هنگام ستون های بی پایان کد، سر شما را به درد - یا حداقل گیج - می آورد. به نظر شما عالی نیست که در این فایل ها بتوانید به سرعت قسمت های مهم کد را پیدا کنید؟

$dir1 = "/home/"; // set main home directory
$myCurrentDir = getCurDirr(); // set the current user directory
$userVar = $get_username(); // current user's username

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

اگر عملکرد فانکشنی مبهم است، گرچه می توانید کاری مشابه بالا (کامنت های این لاین) در داخل فانکشن ها بکنید اما این کار ممکن است کمی کدتان را بهم بریزد که در تقابل با اصل نظم است. پس توصیه می کنیم در این زمان از بلاک های توضیح مانند مثال زیر استفاده کنید:

$(document).ready(function() {
$('.sub').hide(); // hide sub-navigation on pageload
/** check for a click event on an anchor inside .itm div
prevent the default link action so the page doesn't change on click
access the parent element of .itm followed by the next .sub list to toggle open/close
**/
$('.itm a').live('click', function(e){
e.preventDefault();
$(this).parent().next('.sub').slideToggle('fast');
});
});

در بالا یک کد جی کوییری را می بینیم که برای یک منو (menu) نوشته شده. کامنت اول که این لاین است، توضیح می دهد، کلاس sub را پنهان (hide) کرده ایم. و سپس قبل از شروع کد اصلی بلاک توضیحی نوشته و آن را نسبت به سایر نوشته ها جلوتر آورده ایم (indent). این کار متن را زیباتر و خواناتر می کند، خصوصا برای آنهایی که چیزی از کد نمی فهمند و فقط قصد خواندن کامنت ها را دارند.

۳. کامنت ها را هنگام کدنویسی بگذارید

کامنت گذاری هنگام کدنویسی یکی از بهترین عادت ها است. هیچ کس دوست ندارد پس از نوشتن یک برنامه و مطمئن شدن از کارکرد آن، به سراغ کدش برود و توضیح بنویسد. بسیاری از ما حتی می ترسیم طرف چنین کد - بدون کامنت - گیج کننده ای برویم زیرا کامنت گذاری آن زحمت زیادی می برد.

901015-www-Narenji-ir-Source-Code-Comment-Styling-3.jpg

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

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

۴. در پایان کدنویسی

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

901015-www-Narenji-ir-Source-Code-Comment-Styling-4.jpg

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

کامنت گذاری در این زمان به دو دلیل اهمیت دارد: اول اینکه بدانید کجا کار را قطع کرده اید و دفعه بعد که با نیروی تازه به سراغ کد آمدید، دقیقا بدانید به چه گیر کرده بودید (نباید این سوال برای شما ایجاد شود که «خببب کجا بودم؟»).
دوم، برای افتراق دادن کدتان از سایر کدهایی که مشکلی ندارند و به خوبی کار می کنند.
به خاطر داشته باشید، هنگام کامنت گذاری باید توضیح دهید «چرا دارید فلان کد را می نویسید»، نه اینکه دقیقا توضیح دهید «کد چه کاری انجام می دهد».

۵. جمع بندی

طراحی اپلیکیشن (application) ها و نرم افزارهای تحت وب بهترین تمرین برای یادگیری کامنت گذاری هستند. برای تبدیل شدن به یک دولوپر عالی فقط تمرین کدنویسی کافی نیست، باید مهارت های کامنت گذاری را نیز در خودتان تقویت کنید. کامنت گذاری با توضیح کامل، نیاز به تمرین طولانی مدت دارد، اما زمانی که آن را خوبی یاد گرفتید هرگز رهایش نخواهید کرد.


منبع
[عکس: <a href=www.Mojsazan.com.gif]" class="mycode_img" />
پاسخ
سپاس شده توسط Nikkhahan


موضوعات مشابه ...
موضوع نویسنده پاسخ بازدید آخرین ارسال
  تزریق وابستگی (dependency injection) به زبان ساده مهرداد عباسی 7 13,327 12-04-2013, 05:41 PM
آخرین ارسال: مهرداد عباسی
Question انتخاب یک زبان جامع برنامه نویسی موبایل - اپلیکیشن - وب - هوش digicom 19 22,933 08-25-2013, 07:10 PM
آخرین ارسال: مهدی ابراهیمی
  کدام زبان برنامه‌ نویسی را یاد بگیریم؟ (راهنمای انتخاب زبان برنامه نویسی) مهرداد عباسی 0 3,645 09-22-2012, 07:06 PM
آخرین ارسال: مهرداد عباسی
  تاریخچه زبان های برنامه نویسی مهرداد عباسی 0 2,526 09-20-2012, 11:08 PM
آخرین ارسال: مهرداد عباسی
  مقایسه بین دو زبان برنامه نویسی؟ rector 6 8,166 08-14-2012, 03:10 PM
آخرین ارسال: kakolokia
  زبان برنامه نویسی محبوب دنیا در سال ۲۰۱۲ مهرداد عباسی 0 2,820 08-02-2012, 10:52 PM
آخرین ارسال: مهرداد عباسی
  انتخاب یک زبان C++ یا C# کدام بهتر است؟ alamdar_313 27 33,764 05-03-2012, 04:41 PM
آخرین ارسال: مهرداد عباسی
  رتبه زبان های برنامه نویسی (بازگشت C به رتبه اول) مهرداد عباسی 4 6,290 05-02-2012, 11:25 PM
آخرین ارسال: مهرداد عباسی
  پند‌هایی از ده توسعه‌دهنده حرفه‌ای و بزرگ زبان PHP مهرداد عباسی 0 3,023 06-28-2011, 03:30 PM
آخرین ارسال: مهرداد عباسی
  كدام زبان برنامه ‌نویسی را انتخاب كنیم؟ مهرداد عباسی 0 3,033 12-16-2009, 01:55 AM
آخرین ارسال: مهرداد عباسی

پرش به انجمن:


کاربران در حال بازدید این موضوع: 1 مهمان