لطفا جاواسکریپت مرورگر خود را فعال سازید!

نحوه فعال سازی در کروم
  1. ابتدا باید اینکارو بگنید
  2. بعدش اونکارو
نحوه فعال سازی در فایرفاکس
  1. ابتدا باید اینکارو بگنید
  2. بعدش اونکارو
راهنمای گوگل برای کامنت‌گذاری سورس‌کد

راهنمای گوگل برای کامنت‌گذاری سورس‌کد

در صنعت توسعهٔ نرم‌افزار، همواره یکسری به‌اصطلاح Best Practice که به‌نوعی می‌شود آن‌را «بهترین راه‌کار» ترجمه کرد وجود دارد که پیروی از آن‌ها منجر به بهینه‌تر شدن سورس‌کد می‌شود؛ سال‌ها پیش یکسری Googler (دولوپرهای گوگل) دور هم جمع شدند تا بر این مشکل فائق آیند و نتیجه این شد که گروهی موسوم به Code Health ایجاد گردید.

گروه Code Health راه‌کارهای مفید زیادی برای بهبود سورس‌کد ارائه داده که یکی از آن‌ها، شیوهٔ کامنت‌گذاری صحیح سورس‌کد است؛ وقتی سورس‌کد نرم‌افزاری را می‌خوانیم، گاهی‌اوقات هیچ‌چیز مفیدتر و ارزشمندتر از یک کامنت خوب نیست اما درعین‌حال به‌خاطر داشته باشیم که کامنت‌ها همیشه هم خوب نیستند!

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

- از داخل کد، یک فانکشن بیرون بکشید
برای روشن‌تر شدن این مسئله، ابتدا کد زیر را ملاحظه کنید:

// Filter offensive words.
for (String word : words) { ... }

همان‌طور که ملاحظه می‌شود، کامنتی نوشته‌ایم که در مورد حلقهٔ for توضیحات تکمیلی می‌دهد اما این‌ درحالی است که به‌سادگی می‌توان این حلقه را به‌صورت یک فانکشن درآورده که نامش خود گویای ماهیتش است که در این صورت داریم:

filterOffensiveWords(words);

- استفاده از اسامی توصیفی
در کد زیر از طریق یک کامنت توضیح داده‌ایم که واحد اعداد قرار گرفته در متغیر width باید به‌صورت پیکسل باشد:

int width = ...; // Width in pixels.

اما این درحالی است که می‌توانیم این واحد عددی را در خود نام متغیر به‌صورت زیر بگنجانیم:

int widthInPixels = ...;

- چک کردن برخی فرضیات
در کد زیر، گفته‌ایم اگر مقدار متغیر height بزرگ‌تر از ۰ بود، خارج‌قسمت width تقسیم‌بر height بازگردانده شود:

// Safe since height is always > 0.
return width / height;

اما به‌سادگی با قرار دادن یک if می‌توانیم این کامنت را حذف کنیم که در این صورت داریم:

if(height > 0) {
    return width / height;
}

در پایان هم به‌خاطر داشته باشیم که همواره از کامنت‌هایی که دقیقاً عملکرد کد را تکرار می‌کنند خودداری کنیم؛ به‌عنوان نمونه داریم:

// Get all users.
userService.getAllUsers();

و یا:

// Check if the name is empty.
if (name.isEmpty()) { ... }

حال نوبت به نظرات شما می‌رسد اما پیش از آن توصیه می‌کنیم مقاله‌ای تحت‌عنوان آیا روش مورد تأییدی برای کامنت‌گذاری در کدها وجود دارد؟ را نیز مطالعه نمایید که در آن دیدگاه‌هایی که دولوپرها را در این حوزه به ۲ دستهٔ کلی تقسیم می‌کنند معرفی شده‌اند. با این توضیحات، به‌نظر شما چه به‌اصطلاح Best Practiceهای دیگری برای کامنت‌گذاری حرفه‌ای سورس‌کد وجود دارد؟ نظرات، دیدگاه‌ها و تجربیات خود را با ما و سایر کاربران سکان به اشتراک بگذارید.

منبع