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

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

🐍 HomeOfPython
|
📅 1404/10/20

سطح مقدماتی (Beginner Level)

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

۱. کامنت‌های تک‌خطی (Single-line Comments)

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

کاربرد اول: توضیح منطق کد

گاهی لازم است بگوییم کد چه کاری انجام می‌دهد (اگر کد پیچیده باشد).

Python

کاربرد دوم: غیرفعال کردن کد (Comment Out)

هنگام تست کردن، می‌توانید بخشی از کد را با # غیرفعال کنید تا اجرا نشود.

Python

۲. کامنت‌های بین‌خطی (Inline Comments)

این کامنت‌ها در همان خطی که کد نوشته شده است قرار می‌گیرند. طبق استاندارد PEP 8، باید بین انتهای کد و علامت # حداقل دو فاصله (Space) وجود داشته باشد.

Python
python 
# Static Example (Bad Practice vs Good Practice)
x = x + 1 # Increment x (This is obvious and bad comment)
x = x + 1  # Adjust for zero-based indexing (This explains WHY and is good)

۳. کامنت‌های چندخطی (Multi-line Comments)

پایتون سینتکس اختصاصی برای کامنت بلوکی ندارد، اما دو روش رایج وجود دارد:

روش اول: استفاده از چندین # (توصیه شده)

این روش استانداردترین راه برای نوشتن توضیحات طولانی است.

python 
# This is a multi-line comment.
# We are explaining a complex algorithm here.
# It helps readability.
def complex_logic():
    pass

روش دوم: استفاده از رشته‌های چندخطی (توصیه نمی‌شود)

برخی برنامه‌نویسان از """ استفاده می‌کنند. اگر این رشته به هیچ متغیری اختصاص نیابد، پایتون آن را نادیده می‌گیرد؛ اما از نظر فنی این یک "رشته" است، نه کامنت.

Python

سطح پیشرفته (Professional Level)

در سطح حرفه‌ای، تفاوت بین "توضیح برای توسعه‌دهنده" (Comment) و "مستندات استفاده از کد" (Docstring) حیاتی است. همچنین نحوه دسترسی برنامه‌نویسی به مستندات و استانداردهای نوشتن آن‌ها بررسی می‌شود.

۱. داک‌استرینگ‌ها (Docstrings)

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

دسترسی به داک‌استرینگ با __doc__

شما می‌توانید متن مستندات را در زمان اجرا بخوانید.

Python

استفاده از تابع help()

ابزارهای پایتون و تابع help() از داک‌استرینگ برای راهنمایی کاربر استفاده می‌کنند.

Python

۲. استانداردهای نوشتن Docstring (PEP 257)

نوشتن داک‌استرینگ سلیقه‌ای نیست. فرمت‌های معروفی مانند Google Style، NumPy Style و reStructuredText (Sphinx) وجود دارند.

Google Style (محبوب و خوانا)

در این فرمت، بخش‌ها با نام‌های Args و Returns جدا می‌شوند.

python 
def calculate_vat(price, rate=0.09):
    """
    Calculates the Value Added Tax (VAT).

    Args:
        price (float): The net price of the item.
        rate (float): The tax rate (default is 0.09).

    Returns:
        float: The calculated tax amount.
        
    Raises:
        ValueError: If price is negative.
    """
    if price < 0:
        raise ValueError("Price cannot be negative")
    return price * rate

NumPy Style (مناسب پروژه‌های علمی)

مناسب برای توابع با پارامترهای زیاد و توضیحات ریاضی.

python 
def normalize(vector):
    """
    Normalize a vector.

    Parameters
    ----------
    vector : list
        Input vector to normalize.

    Returns
    -------
    list
        Normalized vector.
    """
    pass

۳. تگ‌های خاص کامنت‌گذاری (TODO, FIXME)

در پروژه‌های بزرگ تیمی، از تگ‌های خاصی برای نشان دادن وضعیت کد استفاده می‌شود. اکثر IDEها (مثل VS Code یا PyCharm) این تگ‌ها را هایلایت می‌کنند.

  • TODO: کاری که باید در آینده انجام شود.
  • FIXME: کدی که ایراد دارد و باید سریعاً اصلاح شود.
  • NOTE: نکته‌ای برای توجه ویژه.
python 
# Example of tags used in professional codebases

def process_data(data):
    # TODO: Add validation for empty lists
    if not data:
        return None
    
    # FIXME: This calculation is slow for large datasets
    result = [x * 2 for x in data] 
    
    return result

۴. اصول Clean Code در کامنت‌نویسی

یکی از مهم‌ترین اصول حرفه‌ای این است: "کد بد را کامنت نکنید، آن را بازنویسی کنید."

کامنت‌ها باید بگویند چرا (Why) یک کار انجام شده است، نه اینکه چگونه (How) انجام شده (چون خود کد نشان‌دهنده چگونگی است).

مثال بد (Bad Comment):

python 
# Check if user is over 18
if user.age > 18:
    pass

چرا بد است؟ چون کد user.age > 18 خودش واضح است.

مثال خوب (Refactoring instead of Comment): به جای کامنت، نام متغیر را اصلاح کنید تا کد خودتوصیف (Self-documenting) شود.

Python
← بازگشت به لیست آموزش‌ها