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

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

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

علت نوشتن برنامه و هدف آن
مشخصات برنامه‌نویس
مخاطبان برنامه و کاربرانی که برنامه برای آن‌ها مفید خواهد بود
نحوهٔ سازماندهی برنامه و نوشتن کدها
نحوهٔ کارکرد سورس‌کد برنامه
لایبرری‌هایی که در برنامه از آن‌ها استفاده شده است و ...

مستندات یک برنامه در قالب‌های مختلفی ارائه می‌شوند که در این آموزش قصد داریم به مستنداتی بپردازیم که به صورت کامنت در میان کدهای برنامه نوشته می‌شوند (برای آشنایی با انواع مختلف مستندات نرم افزار و ابزارهای آن، به مقاله مستند‌سازی نرم افزار مراجعه کنید).

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

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

نکته

بر اساس استاندارد کدنویسی زبان برنامه‌نویسی پایتون، بهتر است بعد از قرار دادن علامت هشتگ یک فضای خالی (اِسپیس) قرار دهید سپس متن توضیح را وارد کنید.

برای درک بهتر این موضوع، کدهای زیر را در پنجرهٔ تعاملی IDLE وارد می‌کنیم:

>>> # This is a comment
>>> This is a comment
SyntaxError: invalid syntax

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

علاوه بر اینکه یک کامنت می‌تواند از ابتدای سطر آغاز شود، امکان شروع کامنت از نیمهٔ سطر نیز وجود دارد. به طور مثال، در اسکریپت زیر طول و عرض مستطیلی را به ترتیب در متغیرهای length و width ذخیره کرده سپس مساحت مستطیل را که حاصل‌ضرب این دو متغیر است را در متغیری با نام area ذخیره می‌سازیم:

>>> length = 2
>>> width = 3
>>> area = length*width # This Calculates the area of the rectangle

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

دقت کنید که در این روش بهتر است بین کدهای دستوری و کاراکتر # که آغازگر توضیحات است حداقل دو اِسپیس قرار دهیم تا خوانایی برنامه بهتر شود. واضح است که اگر بخواهیم توضیحات خود را در چند خط بیاوریم لازم است در شروع هر خط جدید یک کاراکتر # قرار دهیم به طوری که داریم:

>>> # This is a comment.
>>> # Python ignores anything after #,
>>> # so this line of code won't run.

از آنجا که می‌توانیم هر متنی را در قالب یک کامنت در سورس‌کد برنامهٔ خود وارد کنیم، یکی از کاربردهای امکان درج توضیحات در برنامه‌ها این است که می‌توانیم بخشی از کدهایی که قبلاً نوشته‌ایم را به صورت موقت غیرفعال کنیم تا اجرا نشوند که برای این کار کافی است یک کاراکتر # قبل از دستور مد نظر قرار دهیم (گاهی اوقات این کار در پیدا کردن خطاهای برنامه کمک زیادی خواهد کرد.)

نکته

دقت داشته باشید در حالتی که کدها را در پنجره‌ی تعاملی یا شِل IDLE وارد می‌کنیم، امکان ویرایش مجدد آن‌ها را نداریم و این روش غیرفعال کردن کدها برای حالتی است که کدها را به صورت اسکریپتی وارد می‌کنیم.

حال فرض کنیم بخواهیم تعداد زیادی از خطوط کد را به این روش غیرفعال کنیم و از آنجا که قرار دادن کاراکتر # در ابتدای هر سطر کمی وقت‌گیر است، در این مورد بعضی از برنامه‌نویسان به این شیوه عمل می‌کنند که به جای درج کاراکتر # در آغاز هر خط، کدهای نوشته‌شده را بین علامت‌های نقل‌قول """ یا ''' قرار می‌دهند. برای مثال، اگر کد زیر را در پنجرهٔ تعاملی IDLE وارد کنیم، مفسر پایتون نتیجهٔ عملیات را محاسبه می‌کند و مقدار آن را ریترن می‌کند:

>>> 6 * (5 - (18 % 7)) + 4
10

حال اگر همین قطعه کد را در میان علامت‌های نقل‌قول فوق قرار دهیم، مفسر پایتون آن را تنها به عنوان یک استرینگ می‌بیند و عملیات محاسباتی قبلی را اجرا نخواهد کرد:

>>> """6 * (5 - (18 % 7)) + 4"""
'6 * (5 - (18 % 7)) + 4'

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

در کل، شاید این موضوع که مفسر پایتون کامنت‌ها را نادیده می‌گیرد کمی آن‌ها را برای ما بی‌اهمیت کند اما باید توجه داشته باشیم که درج توضیحات مناسب در برنامه‌ها، با خواناتر کردن سورس‌کد کمک زیادی به ما و سایر برنامه‌نویسانی که بخواهند بعداً روی برنامه‌ی ما کار کنند خواهد کرد که در همین راستا توصیه می‌کنیم به مقاله‌ی ۸ قانون برای نوشتن Documentation (مستندات) خوب در وبلاگ سکان آکادمی مراجعه نمایید.

آشنایی با مستندسازی برنامه‌هایی که با پایتون می‌نویسیم