خوانایی بیشتر کد، با توضیحات مناسب

اگر کمی اهل وب گردی و گیت هاب باشید، و گهگاهی سورس کد پروژه ها را ببینید، متوجه میشوید که چقدر ساده میتوان آنها را فهمید (نسبت به درصد کمی از کد های دیگر). اما چه چیزی این ها را متمایز میکند؟

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

کد، خودش خود را توضیح میدهد

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

حافظه ی ما حافظ نیست

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

اکنون که با برخی دلایل توضیح نویسی در کد آشنا شدید، بهتر است ببینیم که در نوشتن توضیحات رعایت چه نکاتی باعث خواناتر شدن آن میشود.

این فایل چیه؟

هر فایل کد باید با یک توضیح در مورد کلیت آن فایل، نویسنده، نسخه و مجوز شروع شود. به خطوط توضیح زیر که ابتدای یک فایل آمده اند توجه کنید (در این مطلب از ++Cاستفاده شده):

/**
  * CalcObject class header
  * calcobject.h
  * Purpose: It`s used for vreating objects of type CalcObject to do 
  *          Calcualtions.
  * @author Ali_RNT (Ali Rashidi)
  * @version 0.2 October 12th 2016
  * This file is published under GNU GPL v3 license.
*/

توضیحات در مورد توضیحات:

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

• در خط اول عنوان فایل
• در خط دوم نام فایل را بنویسید. اگر از برنامه های بازیابی اطلاعات استفاده کرده باشید علتش را میدانید. بعد از بازیابی گاهی نام فایل ها از بین میرود.
• هدفتان از این فایل و کاربرد آنرا بنویسید.
• از تگ author@ برای معرفی نویسنده و تگ version@ برای اعلام نسخه استفاده کنید.

تگ های استفاده شده در کامنت ها خیلی مهم هستند. اگر از این کلاس ها در IDE ها استفاده کنید میبینید که برخی اطلاعات این تگ ها را میخوانند و در مورد فایل میگویند. حتی وقتی در Qt Creator یا ویژوال استودیو، توضیحات یک متد را به شما نشان میدهد، با استفاده از همین تگ هاست.

توابع تابع توضیحات

قبل از هر تابع یا متد، در قالب زیر در مورد آن توضیح دهید:

/**
  * @desc Adds two numbers and returns sum.
  * @param a First number b Second number
  * @return int Sum of the given numbers
*/
int getSum(int a, int b)
{
...

کاربرد تگ های استفاده شده هم واضح است.

کوچکترین جزئیات

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

//Find sum of numbers
sum = a + b;

و نکته ی آخر

علاوه بر آخرین مثالی که دیدید، برخی ترجیح میدهند توضیح هر خط را جلوی آن (نه بالای آن) بنویسند که کار پسندیده ای است! اما به شرطی که قابل خواندن باشد. به دو تکه کد زیر دقت کنید:

int finalVal = getSum( i, n - i); //store the sum in finalVal
if (finalVal) cout << "1\n"; //print 1 if finalVal is not 0
else cout << "0\n"; //Othervise print 0

int finalVal = getSum( i, n - i);   //store the sum in finalVal
if (finalVal) cout << "1\n";        //print 1 if finalVal is not 0
else cout << "0\n";                 //Othervise print 0