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

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

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

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()) { ... }

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