سلام به همه دوستان برنامه نویس: ) واقعیتش من چند وقتی بود که داشتم کتاب"" یا همان را می‌خوندم و دیدم خیلی کتاب مفیدی هست و بد نیست که برنامه‌نویسان عزیز این کتاب را بخوانند، برای همین تصمیم گرفتم کتاب را ترجمه کنم و چند فصل از کتاب را هم توی ویرگول منتشر می‌کنم. امیدوارم مفید باشه و برنامه نویسان عزیزی مثل شما بعد از خوندن این کتاب کدهای تمیزتری بنویسید و کمی به شما در مسیر پیشرفت توی حوزه برنامه‌نویسی کمک کند. خب در این پست ویرگولی بخش دوم کتاب هنر کدنویسی خوانا که با موضوع را با هم دنبال می‌کنیم: خودتان را جای خواننده بگذارید یک تکنیک کلی که در این کتاب استفاده می‌کنیم این است که "، کسی که به اندازه شما با این پروژه آشنا نیست. این تکنیک به ویژه برای تشخیص اینکه چه بخش‌هایی نیاز به کامنت گذاری دارند به شما کمک می‌کند. پیش بینی سوالات احتمالی هنگامی که شخص دیگری کد شما را بخواند، بخش‌هایی وجود دارد که ممکن است در مورد بخش‌هایی از آن به این صورت فکر کند که " کار شما این هست که این بخش‌ها را کامنت گذاری کنید. به عنوان مثال نگاهی به تعریف تابع ( Clear بیندازید: اکثر برنامه‌نویسان C ++ در هنگام مواجه با این کد به این فکر خواهند کرد که: چرا در آن به جای تعویض با یک بردار خالی، فقط از ( data . clear استفاده نشده است؟ خب معلوم است که این تنها روش مجبور کردن یک بردار است، تا به درستی حافظه خود را به حافظه allocator رها سازی کند. این کار از جزییات C ++ است که به خوبی شناخته نشده است. بنابراین، باید اینگونه کامنت گذاری شود: اعلام کردن تله احتمالی هنگام مستند کردن یک تابع یا یک کلاس، سوال خوبی که می‌توانید از خود بپرسید این است که، چه چیز تعجب آوری در مورد این کد وجود دارد؟ چگونه ممکن است این کد سبب برداشت اشتباه خواننده شود؟ در واقع، شما دارید "به آینده فکر می‌کنید" تا مشکلاتی که احتمالا افراد در زمان استفاده از کد، به آن دچار می‌شوند را پیش بینی کنید. به عنوان مثال، فرض کنید تابعی نوشته‌اید که یک ایمیل را به کاربری معین ارسال می‌کند: پیاده سازی این تابع شامل اتصال به یک سرویس ایمیل خارجی است که ممکن است یک ثانیه کامل یا بیشتر زمان ببرد. شخصی که در حال نوشتن یک برنامه کاربردی وب است ممکن است متوجه این موضوع نشده و اشتباها این تابع را حین انجام درخواست HTTP فراخوانی کند که در صورت قطع سرویس ایمیل، انجام این کار سبب توقف برنامه کاربردی وب می‌گردد. برای جلوگیری از این اشتباه احتمالی، باید در مورد جزییات پیاده سازی شده کامنت گذاری کنید: در اینجا مثال دیگری داریم، فرض کنید تابع ( FixBrokenHtml را دارید که تلاش می‌کند کدهای HTML دارای اشکال را با افزودن تگ بسته شدن به انتهای آن‌ها، بازنویسی کند: این تابع در غیر از مواردی که حین اجرای آن تگ‌های بدون همتا و تو در توی بسیار زیادی وجود داشته باشد، خیلی عالی عمل می‌کند ولی برای ورودی‌های بهم ریخته و کثیف HTML اجرای این تابع می‌تواند چند دقیقه طول بکشد. به جای اینکه اجازه دهید کاربر خودش بعدها متوجه این موضوع شود، بهتر است که در یک کامنت و در همان ابتدای کار در مورد سرعت اجرای آن هشدار دهید: کامنت‌های روند کلی یکی از سخت‌ترین موارد برای عضو جدید تیم، فهمیدن روند کلی برنامه است. اینکه تعامل کلاس‌ها چگونه است، جریان داده در کل سیستم به چه صورت بوده و نقاط ورودی کجاها هستند. طراح اصلی سیستم به دلیل درگیری زیاد با این موارد معمولا فراموش می‌کند که درباره آن‌ها کامنت گذاری کند. حال بیایید این آزمایش فکری را در نظر بگیرید: شما در حال ارایه توضیحات در مورد کدپایه، ممکن است به فایل‌ها و کلاس‌های خاصی اشاره کنید و چیزی شبیه این جملات را بگویید: این کد واسط بین منطق بیزینس ما و دیتابیس است. هیچ کد اپلیکیشنی نباید از این کد مستقیما استفاده کند. این کلاس به نظر پیچیده می‌رسد، اما این در واقع یک Cache هوشمند است و در مورد بقیه سیستم چیزی نمی‌داند. پس از یک دقیقه مکالمه غیر جدی، عضو جدید تیم نسبت به زمانی که خودش به تنهایی می‌خواست سورس کد را بخواند، اطلاعات خوبی در مورد سیستم بدست می‌آورد. در اینجا یک مثال ساده از کامنت سطح - فایل داریم: از این فکر که حتما مجبور هستید یک سند رسمی و وسیع بنویسید نگران نشوید. کامنت‌های خلاصه این ایده خوبی است که حتی در عمق یک تابع، در مورد تصویر کلی‌تر آن، کامنت گذاری کنید. در اینجا مثالی از یک کامنت آورده شده است که کد سطح - پایین زیر آن را به صورت خلاصه بیان می‌کند: بدون این کامنت، خواندن هر خط از کد مقداری رمزآلود خواهد شد چرا که به نظر می‌رسد از طریق all _ customers . در حال تکرار هستیم و این سوال پیش می‌آید که "این تکرار برای چیست؟ ". این کار زمانی مفید است که کامنت‌های خلاصه را در یک تابع بزرگتر داشته باشیم، جایی که تعدادی از تکه‌های بزرگ کد داخل آن‌ها وجود دارد. همچنین این کامنت‌ها می‌توانند به عنوان گزارش‌هایی خلاصه از اینکه توابع چه کاری انجام می‌دهند، عمل کنند، بنابراین قبل از اینکه خواننده وارد جزییات تابع شود، می‌تواند به طور خلاصه کار انجام گرفته توسط تابع را بفهمد (البته اگر این تکه‌ها به آسانی قابل جدا شدن از یکدیگر هستند، بهتر است که آن‌ها را به شکل توابع جداگانه بنویسید. همان‌گونه که قبلا اشاره کردیم، کد خوب بهتر از کد بد با کامنت خوب است) دلایل کامنت گذاری: برای چه چیزی؟ چرا؟ یا چگونه؟ ممکن است توصیه‌های سختگیرانه‌ای از این دست را شنیده باشید که: کامنت گذاری باید برای " باید انجام شود" باشد و نه برای. این توصیه اگرچه قابل توجه است ولی ما فکر می‌کنیم که این دستورات خیلی ساده هستند و برای افراد مختلف معنای متفاوتی می‌دهند. توصیه ما این است که هر کاری که به خواننده برای درک ساده‌تر کد کمک می‌کند را انجام دهید. این امر ممکن است شامل کامنت گذاری در مورد و یا حتی شامل هر سه این موارد باشد. افکار نهایی، گذر از بلوک نویسنده بسیاری از برنامه‌نویسان کامنت نویسی را دوست ندارند چرا که احساس می‌کنند باید کار زیادی برای نوشتن یک کامنت خوب، انجام شود. بهترین راه‌حل در مواجهه با این مانع احساسی این است که شروع به نوشتن کنید. بنابراین دفعه بعدی که در مورد نوشتن کامنت تردید داشتید، فقط جلو رفته و کامنتی در این مورد این که به چه چیزی فکر می‌کنید بنویسید، هرچند که کامل نباشد. به عنوان مثال فرض کنید شما روی یک تابع کار می‌کنید و با خود می‌اندیشید که. فقط همین را به عنوان کامنت بنویسید: دیدید! خیلی سخت نبود. در واقع کامنت بدی هم نبود، هرچند کمی مبهم است ولی مطمینا بهتر از هیچ است. برای حل این مشکل نیز می‌توانیم هر عبارت را مرور کرده و یک چیز خاص‌تر را جایگزین آن کنیم: کلمه‌ای با معنی واقعی‌تر برای! همچون این عبارت: مراقب باشید: این چیزی است که باید بیشتر مراقب آن باشید. کلمه‌ای با معنی دقیق‌تر نیز برای همچون این عبارت: کدی که این ورودی را مدیریت می‌کند. عبارتی رساتر برای خواهد بود همچون این عبارت: پیاده سازی آن سخت خواهد بود. احتمالا کامنت جدید به این صورت خواهد بود: توجه داشته باشید که ما نوشتن یک کامنت را به سه مرحله ساده تقسیم کردیم: هرچیزی که به عنوان کامنت در مغز شما است را بنویسید. کامنت را بخوانید، و هر چیزی را که نیازمند بهبود است، بهبود دهید. کل کامنت را بهبود دهید. هر چه کامنت بیشتری بنویسید، متوجه خواهید شد که کیفیت کامنت‌ها در هر مرحله بهتر و بهتر می‌شوند و در نهایت ممکن است کامنت شما اصلا نیازی به اصلاح نداشته باشد. همچنین با کامنت گذاری در اوایل و اغلب اوقات، از وضعیت ناخوشایند نیاز به نوشتن یک دسته از کامنت‌ها در پایان، خودداری خواهید کرد.