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


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

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

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

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

نکته
براساس استاندارد کدنویسی زبان برنامه نویسی پایتون، بهتر است بعد از قرار دادن علامت # یک فضای خالی یا Space قرار دهید سپس متن توضیح را وارد کنید.

برای تمرین، کدهای زیر را در پنجره ی تعاملی 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 چه مقداری ذخیره می شود داده شده است. توجه داشته باشید که قبل از درج توضیحات می توان دستور قابل اجرا نوشت اما پس از آن دیگر نمی توانیم تا انتهای خط، دستوری برای اجرا قرار دهیم و هر دستوری بعد از کاراکتر # توسط مفسر نادیده گرفته می شود، بنابراین برای نوشتن یک دستور قابل اجرا باید به خط بعد برویم، چرا که با شروع سطر جدید توضیحات قبلی پایان می یابد.

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

>>> # 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'

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

در این آموزش به بررسی نحوه ی کامنت گذاری در زبان برنامه نویسی پایتون پرداختیم. شاید این موضوع که مفسر پایتون کامنت ها را نادیده می گیرد کمی آن ها را برای ما بی اهمیت کند، با این وجود باید توجه داشته باشیم که درج توضیحات مناسب در برنامه ها، با خواناتر کردن کدها کمک زیادی به ما و سایر برنامه نویسانی که بخواهند بعداً روی برنامه ی ما کار کنند خواهد کرد. 

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

لیست نظرات
کاربر میهمان
دیدگاه شما چیست؟
کاربر میهمان
کاربر میهمان
aminمن یک کاربر مهمان هستم
سکان آکادمی عالیه.........
pakepk
pakepk
عالی است ممنون
aherehef
aherehef
علامت های نقل قول سه گانه برای معرفی نوع داده ی استرینگ به مفسر پایتون...منظور سه تا تک کوتیشن یا سه تا جفت کوتیشن
aherehef
aherehef
عالیه