آموزش پایتون - کامنت ها

کامنت‌ها در پایتون

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

مثال

اگر کد زیر را اجرا کنیم، خروجی تولید شده صرفاً عبارت "Hello, World!" را در کنسول چاپ می‌کند، زیرا کامنت‌ها توسط مفسر پایتون نادیده گرفته می‌شوند و تأثیری بر اجرای برنامه ندارند -

# This is a comment
print("Hello, World!")  

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

• کامنت‌های تک‌خطی
• کامنت‌های چندخطی
• کامنت‌های داک‌استرینگ (Docstring)

کامنت‌های تک‌خطی در پایتون

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

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

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

در این مثال، کامنت تک‌خطی مستقل بالای تابع "greet" قرار گرفته است -

# Standalone single line comment is placed here
def greet():
   print("Hello, World!")
greet()

مثال: کامنت تک‌خطی درون‌خطی (Inline)

کامنت تک‌خطی درون‌خطی کامنتی است که در همان خطِ مربوط به قطعه‌کد، پس از کد و بعد از علامت هش (#) ظاهر می‌شود.

در اینجا، کامنت تک‌خطی درون‌خطی پس از دستور print("Hello, World!") آمده است -

print("Hello, World!")  # Inline single line comment is placed here

کامنت‌های چندخطی در پایتون

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

کامنت‌های تک‌خطی متوالی

کامنت‌های تک‌خطی متوالی به استفاده از علامت هش (#) در ابتدای هر خط اشاره دارد. این روش اغلب برای توضیحات طولانی‌تر یا جدا کردن بخش‌های مختلف کد استفاده می‌شود.

مثال

در این مثال، از چندین خط کامنت برای توضیح هدف و منطق تابع فاکتوریل استفاده شده است -

# This function calculates the factorial of a number
# using an iterative approach. The factorial of a number
# n is the product of all positive integers less than or
# equal to n. For example, factorial(5) is 5*4*3*2*1 = 120.
def factorial(n):
   if n < 0:
      return "Factorial is not defined for negative numbers"
   result = 1
   for i in range(1, n + 1):
      result *= i
   return result

number = 5
print(f"The factorial of {number} is {factorial(number)}")

کامنت چندخطی با استفاده از رشته‌های سه کوتیشن

می‌توانیم از رشته‌های سه کوتیشن (''' یا """) برای ایجاد کامنت‌های چندخطی استفاده کنیم. این رشته‌ها از نظر فنی مقدار رشته‌ای (String Literal) هستند، اما اگر به هیچ متغیری اختصاص داده نشوند یا در عبارات استفاده نشوند، می‌توانند به عنوان کامنت به کار روند.

این الگو اغلب برای کامنت‌های بلاکی یا هنگام مستندسازی بخش‌هایی از کد که نیاز به توضیحات مفصل دارند استفاده می‌شود.

مثال

در اینجا، رشته سه کوتیشن توضیحات مفصلی درباره تابع "gcd" ارائه می‌دهد و هدف و الگوریتم مورد استفاده در آن را توصیف می‌کند -

"""
This function calculates the greatest common divisor (GCD)
of two numbers using the Euclidean algorithm. The GCD of
two numbers is the largest number that divides both of them
without leaving a remainder.
"""
def gcd(a, b):
   while b:
      a, b = b, a % b
   return a

result = gcd(48, 18)
print("The GCD of 48 and 18 is:", result)

استفاده از کامنت‌ها برای مستندسازی

در پایتون، کامنت‌های مستندسازی که با نام داک‌استرینگ (Docstring) نیز شناخته می‌شوند، روشی برای گنجاندن مستندات در داخل کد فراهم می‌کنند. این ویژگی برای توضیح هدف و نحوه استفاده از ماژول‌ها، کلاس‌ها، توابع و متدها بسیار مفید است. استفاده مؤثر از کامنت‌های مستندسازی به سایر توسعه‌دهندگان کمک می‌کند تا بدون نیاز به خواندن تمام جزئیات پیاده‌سازی، کد شما و هدف آن را درک کنند.

داک‌استرینگ‌ها در پایتون

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

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

مثالی از داک‌استرینگ یک تابع

def greet(name):
   """
   This function greets the person whose name is passed as a parameter.

   Parameters:
   name (str): The name of the person to greet

   Returns:
   None
   """
   print(f"Hello, {name}!")
greet("Alice")

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

داک‌استرینگ‌ها با استفاده از ویژگی .__doc__ یا تابع help() قابل دسترسی هستند. این امر مشاهده مستندات هر ماژول، کلاس، تابع یا متد را مستقیماً از طریق شل تعاملی پایتون یا درون خود کد آسان می‌کند.

مثال: استفاده از ویژگی .__doc__

def greet(name):
    """
    This function greets the person whose name is passed as a parameter.

    Parameters:
    name (str): The name of the person to greet

    Returns:
    None
    """
print(greet.__doc__)

مثال: استفاده از تابع help()

def greet(name):
    """
    This function greets the person whose name is passed as a parameter.

    Parameters:
    name (str): The name of the person to greet

    Returns:
    None
    """
help(greet)