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

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

1- Header Comments یا توضیحات سرآمد

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

2- توضیحات مربوط به توابع

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

3- Inline Comments یا توضیحات بین خطوط

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

هشدار

توجه داشته باشید که دقت کنید توضیحات شما تنها منظور کدهایتان را روشن کنند نه این که آن ها را تحت الشعاع قرار دهند. بسیاری از برنامه نویسان تازه کار حتی برای واضح ترین و ابتدایی ترین کدها هم کامنت می نویسند که این کاری بس اشتباه است! نوشتن توضیحات زیاد و مفصل می تواند به مانعی برای خوانایی کدهای شما در آینده تبدیل شود.

کامنت‌گذاری را فراموش نکنید