برای مشاهده یافته ها از کلید Enter و برای خروج از کلید Esc استفاده کنید.

داکیومنتِ کد در پایتون قسمت ۱

میدونیم کد خوب یعنی کدی که خوانا باشه و برای فهمیدنش نیاز به توضیح اضافه ای نباشه. اما کد خوب یک ویژگی دیگه هم داره و اون هم اینه که به خوبی داکیومنت شده باشه.

داکیومنت کردن کد یعنی توضیح در مورد اینکه اون کد میخواد چه کاری بکنه، نه اینکه چطور میخواد اون کار رو انجام بده. نکته مهم دیگه اینه که داکیومنت کردن کد، با کامنت گذاری فرق میکنه. کامنت گذاشتن در کد به هیچ وجه توصیه نمیشه.

به چند دلیل کامنت گذاری در کد توصیه نمیشه:

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

توجه: موارد خیلی نادری هست که نمیتونیم از کامنت گذاشتن امتناع کنیم، مثلا فرض کنید جایی ممکنه در یک لایبرری که در کد استفاده کردیم خطایی رخ بده، در چنین مواردی گذاشتن یک کامنت کوتاه بلامانع است.

داکیومنت کردن کد در پایتون شامل موارد زیر است:

  • توضیح دادن نوع داده ها
  • مثال زدن
  • نشانه گذاری متغیرها

Docstrings

داک‌استرینگ به عبارت ساده یعنی رشته ای از کلمات که جایی در کد(module, class, method, function) قرار می‌گیره تا منطق اون قسمت رو توضیح بده.
اهمیت داک‌استرینگ در پایتون به خاطر dynamically type بودنش بسیار بیشتر است. فرض کنید متدی رو ببینید که دو ورودی دارد، و شما مجبورید که تغییراتی در این متد ایجاد کنید. چطور میتونید متوجه بشید که چه ورودی هایی به این متد پاس بدید؟ پس داکیومنت کردن کد خیلی میتونه در راهنمایی کردن دیگران برای استفاده از کدمون کمک کننده باشه.

به مثال زیر توجه کنید تا متوجه بشید چطور میتونیم در پایتون داک‌استرینگ بنویسیم:

def my_function(): """This is the Docstring""" return None print(my_function.__doc__)

همون طور که توی این مثال دیدید، داک‌استرینگ چیزی جدا از کد نیست و با استفاده از __doc__ بر روی هر آبجکتی میشه به داک‌استرینگش دسترسی پیدا کرد. پس میشه در زمان اجرا یا در زمان کامپایل به داک‌استرینگ دسترسی داشت و از ابزارهایی مثل sphinx میشه برای ساخت مستندات از روی داک‌استرینگ ها استفاده کرد.