سلام به همه دوستان برنامه نویس :)
واقعیتش من چند وقتی بود که داشتم کتاب "هنر کدنویسی خوانا" یا همان The Art of Readable Code را می‌خوندم و دیدم خیلی کتاب مفیدی هست و بد نیست که برنامه‌نویسان عزیز این کتاب را بخوانند، برای همین تصمیم گرفتم کتاب را ترجمه کنم و چند فصل از کتاب را هم توی ویرگول منتشر می‌کنم. امیدوارم مفید باشه و برنامه نویسان عزیزی مثل شما بعد از خوندن این کتاب کدهای تمیزتری بنویسید و کمی به شما در مسیر پیشرفت توی حوزه برنامه‌نویسی کمک کند.
اگر بخش اول این فصل را نخوانده‌اید میتونید به نوشته هنر کدنویسی خوانا: چه چیزی را کامنت کنیم؟(بخش اول) مراجعه کنید.
خب در این پست ویرگولی بخش دوم فصل پنجم کتاب هنر کدنویسی خوانا که با موضوع چه چیزی را کامنت کنیم؟ را با هم دنبال می‌کنیم:
یک تکنیک کلی که در این کتاب استفاده می‌کنیم این است که «تصور کنید که کد شما در نظر یک شخص خارجی چگونه به نظر می‌رسد»، کسی که به اندازه شما با این پروژه آشنا نیست. این تکنیک به ویژه برای تشخیص اینکه چه بخش‌هایی نیاز به کامنت گذاری دارند به شما کمک می‌کند.
هنگامی که شخص دیگری کد شما را بخواند، بخش‌هایی وجود دارد که ممکن است در مورد بخش‌هایی از آن به این صورت فکر کند که «هااااااا؟ اینا اصلا در مورد چی هستند؟» کار شما این هست که این بخش‌ها را کامنت گذاری کنید. به عنوان مثال نگاهی به تعریف تابع ()Clear بیندازید:
اکثر برنامه‌نویسان C++ در هنگام مواجه با این کد به این فکر خواهند کرد که: چرا در آن به جای تعویض با یک بردار خالی، فقط از ()data.clear استفاده نشده است؟ خب معلوم است که این تنها روش مجبور کردن یک بردار است، تا به درستی حافظه خود را به حافظه allocator رها سازی کند. این کار از جزئیات C++ است که به خوبی شناخته نشده است. بنابراین، باید اینگونه کامنت گذاری شود:
هنگام مستند کردن یک تابع یا یک کلاس، سوال خوبی که می‌توانید از خود بپرسید این است که، چه چیز تعجب آوری در مورد این کد وجود دارد؟ چگونه ممکن است این کد سبب برداشت اشتباه خواننده شود؟ در واقع، شما دارید «به آینده فکر می‌کنید» تا مشکلاتی که احتمالا افراد در زمان استفاده از کد، به آن دچار می‌شوند را پیش بینی کنید.
به عنوان مثال، فرض کنید تابعی نوشته‌اید که یک ایمیل را به کاربری معین ارسال می‌کند:
پیاده سازی این تابع شامل اتصال به یک سرویس ایمیل خارجی است که ممکن است یک ثانیه کامل یا بیشتر زمان ببرد. شخصی که در حال نوشتن یک برنامه کاربردی وب است ممکن است متوجه این موضوع نشده و اشتباها این تابع را حین انجام درخواست HTTPفراخوانی کند که در صورت قطع سرویس ایمیل، انجام این کار سبب توقف برنامه کاربردی وب می‌گردد.
برای جلوگیری از این اشتباه احتمالی، باید در مورد جزئیات پیاده سازی شده کامنت گذاری کنید:
در اینجا مثال دیگری داریم، فرض کنید تابع ()FixBrokenHtml را دارید که تلاش می‌کند کدهای HTMLدارای اشکال را با افزودن تگ بسته شدن به انتهای آن‌ها، بازنویسی کند:
این تابع در غیر از مواردی که حین اجرای آن تگ‌های بدون همتا و تو در توی بسیار زیادی وجود داشته باشد، خیلی عالی عمل می‌کند ولی برای ورودی‌های بهم ریخته و کثیف HTML اجرای این تابع می‌تواند چند دقیقه طول بکشد.
به جای اینکه اجازه دهید کاربر خودش بعدها متوجه این موضوع شود، بهتر است که در یک کامنت و در همان ابتدای کار در مورد سرعت اجرای آن هشدار دهید:
یکی از سخت‌ترین موارد برای عضو جدید تیم، فهمیدن روند کلی برنامه است. اینکه تعامل کلاس‌ها چگونه است، جریان داده در کل سیستم به چه صورت بوده و نقاط ورودی کجاها هستند.
طراح اصلی سیستم به دلیل درگیری زیاد با این موارد معمولا فراموش می‌کند که درباره آن‌ها کامنت گذاری کند.
حال بیایید این آزمایش فکری را در نظر بگیرید: شخصی به تازگی به تیم شما اضافه شده است، او جلوی شما می‌نشیند تا شما او را با کدپایه آشنا کنید.
شما در حال ارائه توضیحات در مورد کدپایه، ممکن است به فایل‌ها و کلاس‌های خاصی اشاره کنید و چیزی شبیه این جملات را بگویید:
· این کد واسط بین منطق بیزینس ما و دیتابیس است. هیچ کد اپلیکیشنی نباید از این کد مستقیما استفاده کند.
· این کلاس به نظر پیچیده می‌رسد، اما این در واقع یک Cache هوشمند است و در مورد بقیه سیستم چیزی نمی‌داند.
پس از یک دقیقه مکالمه غیر جدی، عضو جدید تیم نسبت به زمانی که خودش به تنهایی می‌خواست سورس کد را بخواند، اطلاعات خوبی در مورد سیستم بدست می‌آورد.
این دقیقا همان نوع اطلاعاتی است که باید به کامنت‌های سطح بالا اضافه شود.
در اینجا یک مثال ساده از کامنت سطح-فایل داریم:
از این فکر که حتما مجبور هستید یک سند رسمی و وسیع بنویسید نگران نشوید. انتخاب چند جمله خوب، بهتر از این است که هیچ چیزی نباشد.
این ایده خوبی است که حتی در عمق یک تابع، در مورد تصویر کلی‌تر آن، کامنت گذاری کنید. در اینجا مثالی از یک کامنت آورده شده است که کد سطح-پایین زیر آن را به صورت خلاصه بیان می‌کند:
بدون این کامنت، خواندن هر خط از کد مقداری رمزآلود خواهد شد چرا که به نظر می‌رسد از طریق all_customers … در حال تکرار هستیم و این سوال پیش می‌آید که «این تکرار برای چیست؟».
این کار زمانی مفید است که کامنت‌های خلاصه را در یک تابع بزرگتر داشته باشیم، جایی که تعدادی از تکه‌های بزرگ کد داخل آن‌ها وجود دارد.
همچنین این کامنت‌ها می‌توانند به عنوان گزارش‌هایی خلاصه از اینکه توابع چه کاری انجام می‌دهند، عمل کنند، بنابراین قبل از اینکه خواننده وارد جزئیات تابع شود، می‌تواند به طور خلاصه کار انجام گرفته توسط تابع را بفهمد(البته اگر این تکه‌ها به آسانی قابل جدا شدن از یکدیگر هستند، بهتر است که آن‌ها را به شکل توابع جداگانه بنویسید. همان‌گونه که قبلا اشاره کردیم، کد خوب بهتر از کد بد با کامنت خوب است).
ممکن است توصیه‌های سختگیرانه‌ای از این دست را شنیده باشید که: کامنت گذاری باید برای «چراباید انجام شود» باشد و نه برای «چه چیزی یا چگونه». این توصیه اگرچه قابل توجه است ولی ما فکر می‌کنیم که این دستورات خیلی ساده هستند و برای افراد مختلف معنای متفاوتی می‌دهند. توصیه ما این است که هر کاری که به خواننده برای درک ساده‌تر کد کمک می‌کند را انجام دهید. این امر ممکن است شامل کامنت گذاری در مورد چه چیزی، چگونه، یا چرا و یا حتی شامل هر سه این موارد باشد.
بسیاری از برنامه‌نویسان کامنت نویسی را دوست ندارند چرا که احساس می‌کنند باید کار زیادی برای نوشتن یک کامنت خوب، انجام شود. بهترین راه‌حل در مواجهه با این مانع احساسی این است که شروع به نوشتن کنید. بنابراین دفعه بعدی که در مورد نوشتن کامنت تردید داشتید، فقط جلو رفته و کامنتی در این مورد این که به چه چیزی فکر می‌کنید بنویسید، هرچند که کامل نباشد.
به عنوان مثال فرض کنید شما روی یک تابع کار می‌کنید و با خود می‌اندیشید که: لعنت بهش، اگر تکراری در این لیست وجود داشته باشد، این چیزها دچار مشکل خواهد شد. فقط همین را به عنوان کامنت بنویسید:
دیدید! خیلی سخت نبود. در واقع کامنت بدی هم نبود، هرچند کمی مبهم است ولی مطمئنا بهتر از هیچ است. برای حل این مشکل نیز می‌توانیم هر عبارت را مرور کرده و یک چیز خاص‌تر را جایگزین آن کنیم:
· کلمه‌ای با معنی واقعی‌تر برای لعنت بهش! همچون این عبارت: مراقب باشید: این چیزی است که باید بیشتر مراقب آن باشید.
· کلمه‌ای با معنی دقیق‌تر نیز برای this stuff همچون این عبارت: کدی که این ورودی را مدیریت می‌کند.
· عبارتی رساتر برای اجرای آن دشوار خواهد بود همچون این عبارت: پیاده سازی آن سخت خواهد بود.
احتمالا کامنت جدید به این صورت خواهد بود:
توجه داشته باشید که ما نوشتن یک کامنت را به سه مرحله ساده تقسیم کردیم:
1. هرچیزی که به عنوان کامنت در مغز شما است را بنویسید.
2. کامنت را بخوانید، و هر چیزی را که نیازمند بهبود است، بهبود دهید.
3. کل کامنت را بهبود دهید.
هر چه کامنت بیشتری بنویسید، متوجه خواهید شد که کیفیت کامنت‌ها در هر مرحله بهتر و بهتر می‌شوند و در نهایت ممکن است کامنت شما اصلا نیازی به اصلاح نداشته باشد. همچنین با کامنت گذاری در اوایل و اغلب اوقات، از وضعیت ناخوشایندِ نیاز به نوشتن یک دسته از کامنت‌ها در پایان، خودداری خواهید کرد.
برای دریافت کامل کتاب با تخفیف ۴۰٪ میتونید از کد تخفیف virgool استفاده کنید. سایت تهیه کتاب
