هنر کدنویسی خوانا: چه چیزی را کامنت کنیم؟(بخش اول)

سلام به همه دوستان برنامه نویس :)

واقعیتش من چند وقتی بود که داشتم کتاب "هنر کدنویسی خوانا" یا همان The Art of Readable Code را می‌خوندم و دیدم خیلی کتاب مفیدی هست و بد نیست که برنامه‌نویسان عزیز این کتاب را بخوانند، برای همین تصمیم گرفتم کتاب را ترجمه کنم و چند فصل از کتاب را هم توی ویرگول منتشر می‌کنم. امیدوارم مفید باشه و برنامه نویسان عزیزی مثل شما بعد از خوندن این کتاب کدهای تمیزتری بنویسید و کمی به شما در مسیر پیشرفت توی حوزه برنامه‌نویسی کمک کند.

خب در این پست ویرگولی فصل پنجم کتاب هنر کدنویسی خوانا که با موضوع چه چیزی را کامنت کنیم؟ است را با هم دنبال می‌کنیم:

فصل پنجم: چه چیزی را کامنت کنیم؟

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

کلید طلایی:
هدف از نوشتن کامنت کمک به خواننده است تا به همان اندازه که نویسنده کد آن را درک کرده، خواننده نیز کد را بفهمد.

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

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

در این فصل به سه بخش مهم خواهیم پرداخت:

• دانستن اینکه چه چیزی را کامنت نکنیم.
• ثبت افکارتان همانند کدنویسی‌تان.
• قرار دادن خودتان به جای خواننده، تا تصور کنید که چه چیزی را باید بداند.

چه چیزی را نباید کامنت کنیم

از آنجا که خواندن یک کامنت زمان زیادتری از خواندن کد برده و فضایی را در بالای صفحه اشغال می‌کند، بهتر است چیزی که مد نظر دارید ارزش کامنت نوشتن را داشته باشد. حال این سوال مطرح می شود که چگونه می‌توان مرز بین یک کامنت بی ارزش و یک کامنت خوب را فهمید؟

تمام کامنت‌های کد زیر بی ارزش هستند:

زیرا هیچ اطلاعات جدیدی را ارائه نداده و هیچ کمکی برای درک بهتر کد به خواننده نمی‌کنند.

کلید طلایی: در مورد حقایقی که خودشان می‌توانند سریعا با خواندن کد به دست آیند، کامنت ننویسید.

البته استفاده از این کلید طلایی نسبی است، به عنوان مثال کامنت زیر را که برای کد پایتون نوشته شده است در نظر بگیرید:

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

فقط برای اینکه کدتان کامنت داشته باشد! کامنت گذاری نکنید

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

همان‌گونه که مشاهده می‌کنید کامنت‌های این کد در دسته کامنت‌های بی ارزش قرار می‌گیرد چرا که تعریف تابع و کامنت نوشته شده تقریبا یکسان هستند. برای بهبود این کد، این کامنت باید حذف شود.

اگر می‌خواهید کامنتی در اینجا داشته باشید، می‌توانید در مورد جزئیات مهم‌تر نیز توضیح دهید:

برای نام‌های بد کامنت ننویسید، در عوض، نام‌های بهتری انتخاب کنید

لازم نیست یک کامنت، بد بودن یک نام را جبران کند. برای مثال، در اینجا یک کامنت بی فایده برای تابعی به نام ()CleanReply نوشته شده است:

بخش اعظم این کامنت در حال توضیح این مطلب است که معنی clean چیست. کافی است به جای آن عبارت «enforce limits» به نام تابع اضافه شود:

نام جدید این تابع اطلاعات مستند زیادی در خودش دارد. به یاد داشته باشید که یک نام خوب، بهتر از یک کامنت خوب است زیرا نام تابع در هرجایی که تابع استفاده شده باشد، دیده می‌شود.

در ادامه مثال دیگری از استفاده کامنت به دلیل انتخاب یک نام ضعیف برای یک تابع را مشاهده می‌کنید:

به نظر می‌رسد نام ()DeleteRegistry شبیه یک تابع خطرناک است(این تابع حافظه registery را delete می‌کند؟!). کامنت نوشته شده به معنی «در واقع این رجیستری را تغییر نمی‌دهد» است و تلاش می‌کند که از گنگ بودن نام تابع، رفع ابهام کند.

به جای آن می‌توانیم از یک نام خود-مستندساز بهتر به صورت زیر استفاده کنیم:

به طول کلی، شما نمی‌خواهید کامنت‌های crutchداشته باشید[1]. کامنت‌های crutch، کامنت‌هایی هستند که سعی می‌کنند ناخوانا بودن کد شما را جبران کنند. کدنویس‌ها اغلب این وضعیت را به شکل یک قانون، این گونه بیان می‌کنند که: «کد خوب بهتر از کد بد + کامنت خوب» است.

ثبت افکار خود

حال که فهمیدید چه چیزی را کامنت نکنید، بیایید در این مورد که چه چیزی را باید کامنت کنیم، بحث کنیم.

اکثر کامنت‌های خوب می‌توانند به سادگی از جمله «ثبت افکار خود» به دست آیند، که شامل مهمترین افکار شما، هنگام نوشتن کد می‌باشند.

افزودن «توضیحات کارگردان»

فیلم‌ها اغلب بخشی با عنوان «توضیحات کارگردان» دارند که در آن فیلم‌ساز بینش خود را ارائه داده و داستان‌هایی را برای کمک به فهمیدن اینکه این فیلم چطور ساخته شده است، بیان می‌کند. به طور مشابه، شما نیز باید کامنت‌ها را برای ثبت دیدگاه‌های با ارزش درباره کد اضافه کنید.

به عنوان مثال این کامنت:

چیزهایی را به خواننده یاد داده و از هرگونه اتلاف وقت آنان جلوگیری می‌کند.

به عنوان مثال دیگر کامنت زیر را در نظر بگیرید:

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

همچنین یک کامنت می‌تواند دلیل عالی نبودن شکل ظاهری کد را شرح دهد:

این کامنت می‌گوید که کد ما کثیف است اما همچنان نفر بعدی را برای ترمیم آن تشویق می‌کند(با ارائه مشخصاتی در مورد چگونگی بهبود آن).

با نبود هیچ کامنتی، خیلی از خواننده‌ها با دیدن کدهای کثیف دچار ترس شده و از دست زدن به آن‌ها خودداری می‌کنند.

نقص‌های موجود در کد خود را کامنت کنید

کد به طور مداوم در حال تغییر و تحول است و در طی این مسیر حتما نقص‌هایی خواهد داشت. از مستند کردن این نقص‌ها خجالت نکشید. مثلا، زمانی که کد نیازمند به بهبودی است می‌توانید از عبارت زیر استفاده کنید:

یا هنگامی که کد کامل نشده است:

برخی از نشانه‌هایی که بین برنامه‌نویسان رایج و محبوب شده‌اند را می‌توانید مشاهده کنید:

ممکن است تیم شما قراردادی برای زمان یا شرط استفاده از این نشانه‌ها داشته باشد. به عنوان مثال TODO ممکن است برای نشان دادن توقف اشکالاتِ رزرو شده باشد. اگر چنین است، پس برای نقص‌های جزئی‌تر می‌توانید بجای TODO از چیزی شبیه todo (با حروف کوچک) و یا maybe-later استفاده کنید.

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

در مورد ثابت‌ها کامنت بنویسید

هنگام تعریف یک ثابت، غالبا این سوال وجود دارد که چرا این متغیر ثابت، مقدار خاصی دارد و مقدار خاص آن چیست؟ به عنوان مثال ممکن است چنین ثابتی را در کد خود ببینید:

به نظر نمی‌رسد که این خط، نیازمند کامنت باشد، اما به احتمال زیاد برنامه‌نویسی که آن را انتخاب کرده است اطلاعات بیشتری در مورد آن می‌داند:

با این کامنت، شخصی که کد را می‌خواند یک راهنما در مورد نحوه تنظیم این متغیر ثابت دارد(به عنوان مثال، تنظیم آن به مقدار ۱ یا ۵۰ احتمالا به ترتیب خیلی کم یا بیش از حد زیاد است).

گاهی اوقات مقدار دقیق یک ثابت به هیچ وجه مهم نیست که در این موارد، وجود یک کامنت، مفید به نظر می‌رسد:

گاهی نیز این ثابت دارای مقداری است که بسیار دقیق تنظیم شده است و احتمالا نباید خیلی تغییر داده شود:

در همه این مثال‌ها ممکن است شما به اضافه کردن کامنت فکر نکرده باشید، اما این کار، کاملا مفید است. برخی از ثابت‌ها هستند که نیاز به کامنت ندارند، زیرا نام آن‌ها به اندازه کافی واضح است(مثلا: SECONDS_PER_DAY). اما تجربه به ما ثابت کرده است که بیشتر ثابت‌ها را می‌توان با افزودن کامنت بهبود داد. مسئله این است که شما در زمان تصمیم گیری در مورد مقداردهی این ثابت به چه چیزی فکر می‌کرده‌اید).

[1] یک اصطلاح به معنی عصای کمکی زیر بغل داشتن است. در اینجا منظور این است که کامنت به عنوان عصای کمکی برای فهماندن کد به خواننده استفاده شود.

نکته پایانی اینکه: پیشاپیش اگر پیشنهاد، انتقاد و تجربه‌ای دارید، خوشحال و ممنون میشم که توی بخش نظرات مطرح کنید.

برای دریافت کامل کتاب با تخفیف ۴۰٪ می‌تونید از کد تخفیف virgool استفاده کنید. سایت تهیه کتاب