نود و هفت چیزی که هر برنامه‌نویسی باید بداند: کامنت‌گذاری را فراموش نکنید


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

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

Header Comments یا توضیحات سرآمد:
هر برنامه باید با یک توضیح آغازین همراه باشد که به آن "توضیحات سرآمد" می گوییم. این توضیحات باید حاوی اطلاعاتی از این قبیل باشند: نام برنامه نویس، تاریخ، نام فایلی که برنامه در آن ذخیره می شود، توضیحی در مورد برنامه و نحوه ی اجرا و استفاده از آن. یکی از بهترین استراتژی ها برای نوشتن برنامه های بزرگ و پیچیده تقسیم کردن کدهای آن در مجموعه فایل های جداگانه ای به نام ماژول است که این کار بررسی و توسعه ی کدها را راحت تر می کند (به طور مثال، سکان آکادمی از ماژول های Application, Tutorial, Blog, Wiki, Jobs, Forum و ... تشکیل شده است.) در این صورت هر فایل نیاز به توضیحات سرآمد دارد که شامل این اطلاعات می شود: نام برنامه نویس، تاریخ، نام فایلی که کدها در آن ذخیره می شوند. هم چنین در این توضیحات باید نام فایل های دیگری که کدهای ماژول کنونی به آن ها وابسته هستند، مثلاً کلاسی را از فایل دیگری به ارث می برند را هم بیاورید.

توضیحات مربوط به توابع:
هر کلاس پیچیده به بخش های کوچک تری تقسیم می شود که به آن ها توابع می گویند و هر تابع مسئول انجام یک وظیفه ی خاص در برنامه است. پیش از معرفی هر تابع، توضیحاتی مربوط به آن نوشته می شود که اطلاعاتی از این قبیل را شامل می شود: تابع قرار است چه کاری را در برنامه انجام دهد، چه ورودی هایی لازم است که به تابع داده شود تا عملیات خود را اجرا کند، و این که تابع در نهایت چه تغییراتی را ایجاد می کند و خروجی آن چه خواهد بود یا اصطلاحاً این تابع چه چیزی را return می کند یا برمی گرداند.

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

هشدار
توجه داشته باشید که دقت کنید توضیحات شما تنها منظور کدهایتان را روشن کنند نه این که آن ها را تحت الشعاع قرار دهند. بسیاری از برنامه نویسان تازه کار حتی برای واضح ترین و ابتدایی ترین کدها هم کامنت می نویسند که این کاری بس اشتباه است! نوشتن توضیحات زیاد و مفصل می تواند به مانعی برای خوانایی کدهای شما در آینده تبدیل شود.
لیست نظرات
کاربر میهمان
دیدگاه شما چیست؟
کاربر میهمان
محسن
محسن
کامت باید واقعا به جا استفاده بشه، موردی که می تونه میزان تجربه و حرفه ای بودن یک دولوپر رو مشخص کنه
یک جمله معروف در برنامه نویسی هست
“Good code is self-documenting.”
به این معنی که کد خوب نیازی به کامنت اضافه نداره، و دقیقا هم همینطوره اگر کد به اندازه کافی خوب و گویا و مرتب نوشته شده باشه و مواردی مثل اسامی متغیرها و توابع،استفاده صحیح از توابع،تورفتگی و بیرون اومدگی در کدهای تودر تو و... رعایت شده باشن، کامنت ها فقط به عنوان توضحات تکمیلی خواهند بود نه بخشی که برای استفاده از کدها و یا تغییرشون باید حتما خونده بشن

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