آموزش جامع کامنت و مستندسازی

🎯 اهداف یادگیری

• تفاوت بین کامنت و مستندسازی را درک کنید
• یاد بگیرید چه زمانی از هر کدام استفاده کنید
• کامنت‌های مؤثر و خوانا بنویسید
• مستندسازی حرفه‌ای با Docstring ایجاد کنید

📌 کامنت‌نویسی چیست؟

کامنت‌ها توضیحاتی هستند که برای برنامه‌نویسان نوشته می‌شوند و پایتون آن‌ها را نادیده می‌گیرد:

# این یک کامنت تک‌خطی است
# برای توضیح کدهای پیچیده استفاده می‌شود
price = 10000  # قیمت به تومان

انواع کامنت‌ها:

• تک‌خطی: با # شروع می‌شود (برای توضیحات کوتاه)
• چندخطی: با سه کوتیشن """ یا ''' (برای توضیحات طولانی)

📌 چه زمانی از کامنت استفاده کنیم؟

# محاسبه تخفیف ویژه برای کاربران قدیمی
# این منطق کسب‌وکار مهمی است که ممکن است تغییر کند
discount = price * 0.15  # 15% تخفیف

قوانین طلایی کامنت‌نویسی:

• توضیح "چرا" نه "چگونه": هدف کد را توضیح دهید نه عملکرد آن را
• کامنت‌های به‌روز: همگام با تغییرات کد، کامنت‌ها را هم اصلاح کنید
• کوتاه و مفید: از توضیحات طولانی و بدیهی خودداری کنید

📌 مستندسازی حرفه‌ای (Docstring)

Docstring برای توضیح توابع، کلاس‌ها و ماژول‌ها استفاده می‌شود و با سه کوتیشن نوشته می‌شود:

def calculate_discount(price, discount_rate):
    """محاسبه قیمت پس از تخفیف
    
    این تابع قیمت نهایی پس از اعمال تخفیف را محاسبه می‌کند.
    
    Args:
        price (float): قیمت اصلی کالا
        discount_rate (float): نرخ تخفیف (بین 0 تا 1)
    
    Returns:
        float: قیمت پس از تخفیف
    
    Raises:
        ValueError: اگر نرخ تخفیف نامعتبر باشد
    """
    if discount_rate < 0 or discount_rate > 1:
        raise ValueError("نرخ تخفیف باید بین 0 و 1 باشد")
    return price * (1 - discount_rate)

اجزای اصلی Docstring:

• توضیح کلی: هدف تابع/کلاس را شرح دهید
• پارامترها (Args): نوع و توضیح هر پارامتر
• مقدار بازگشتی (Returns): نوع و توضیح خروجی
• خطاها (Raises): خطاهای احتمالی که تابع ایجاد می‌کند

📌 تفاوت کامنت و Docstring

📌 تمرین عملی

تابع زیر را با کامنت و Docstring کامل کنید:

def calculate_bmi(weight, height):
    return weight / (height ** 2)

راهنمای تمرین:

# تابع محاسبه شاخص توده بدنی (BMI)
# ورودی:
#   weight: وزن شخص به کیلوگرم
#   height: قد شخص به متر
# خروجی:
#   مقدار BMI محاسبه شده
def calculate_bmi(weight, height):
    """
    محاسبه شاخص توده بدنی (BMI)
    
    پارامترها:
        weight (float): وزن به کیلوگرم
        height (float): قد به متر
    
    برمی‌گرداند:
        float: مقدار BMI محاسبه شده
    
    مثال:
        >>> calculate_bmi(70, 1.75)
        22.857142857142858
    """
    return weight / (height ** 2)

📌 فرآیند حرفه‌ای مستندسازی

فرآیند مستندسازی نرم‌افزار معمولاً شامل دو مرحله اصلی است:

۱. نوشتن کد اولیه

• تمرکز بر پیاده‌سازی: در این مرحله توسعه‌دهندگان روی عملکرد کد تمرکز می‌کنند
• سازماندهی کد: کد به صورت تمیز و قابل فهم نوشته می‌شود
• مستندات اولیه: فقط کامنت‌های ضروری و Docstringهای پایه اضافه می‌شوند

۲. تولید مستندات خودکار

pip install sphinx
sphinx-quickstart
make html

• ابزارهای محبوب: Sphinx (پایتون), Doxygen (چندزبانه), Javadoc (جاوا)
• خروجی ابزارها:
  • توضیحات توابع و کلاس‌ها
  • نوع پارامترها و خروجی‌ها
  • مثال‌های کاربردی
  • راهنمای استفاده

مزایای مستندسازی خودکار:

• سرعت بالا: تولید مستندات در کمترین زمان
• دقت بیشتر: هماهنگی کامل با کد اصلی
• به‌روزرسانی آسان: همگام با تغییرات کد
• فرمت‌های متنوع: خروجی HTML, PDF, ePub و...

📌 قدم بعدی

در درس بعدی با متغیرها و انواع داده در پایتون آشنا خواهیم شد!