توضیحات یا کامنت‌ها خطوطی در برنامه‌های کامپیوتری هستند که توسط کامپایلرها و مفسّرها نادیده گرفته می‌شوند. نوشتن کامنت در برنامه‌ها موجب سهولت در خواندن آنها می‌شود و برخی اطلاعات یا توضیحات در مورد هر کدام از بخش‌های برنامه منتقل می‌گردد.
بسته به هدفی که برنامه شما دنبال می‌کند، کامنت‌ها می‌توانند به عنوان یادداشت برای خودِ برنامه‌نویس، یادآوری و یا جلب توجه برنامه‌نویسان دیگر برای درک عملکرد کدها نوشته شوند.
در حالت کلی باید گفت که نوشتن کامنت در هنگام برنامه‌نویسی یا بروزرسانی برنامه قبلی بسیار مفید است. چرا که با گذشت زمان، به‌راحتی فرآیندها از خاطر می‌روند و کامنت‌هایی که پس از مدتی نوشته می‌شوند، نمی‌توانند چندان مفید باشند.
قالب نوشتن کامنت
کامنت‌ها در پایتون با علامت هشتگ یا # و سپس یک فاصله خالی شروع می‌شوند و تا انتهای خط ادامه می‌یابند.
به طور کلی، کامنت‌ها ظاهری شبیه به زیر خواهند داشت.
# This is a comment
کامنت‌ها اجرا نمی‌شوند. بنابراین وقتی برنامه‌ای را اجرا می‌کنید، نشانه‌ای از وجود کامنت نخواهد داشت. به عبارت دیگر، نوشتن کامنت در کد منبع برای انسان‌هاست نه کامپیوترها.
در یک برنامه “Hello, World!”، یک کامنت ممکن است به صورت زیر باشد.
# Print “Hello, World!” to console
print("Hello, World!")
در یک حلقه for که برای یک لیست تکرار می‌شود، نمونه‌ای از نوشتن کامنت را ملاحظه می‌کنید.
# Define sharks variable as a list of strings sharks = ['hammerhead', 'great white', 'dogfish', 'frilled', 'bullhead', 'requiem'] # For loop that iterates over sharks list and prints each string item for shark in sharks: print(shark)
کامنت‌ها می‌بایست در همان سطح تورفتگی کد برنامه نوشته شوند. به این ترتیب، زمانی که یک تابع بدون تورفتگی وارد شود، کامنت مرتبط با آن نیز بدون توررفتگی خواهد بود. همچنین برای هر سطح تورفتگی در ادامه، کامنتی مطابق با آن نوشته می‌شود.
به عنوان مثال، در اینجا تابع again() را در یک برنامه ماشین حساب ساده با پایتون مشاهده می‌کنید که برای آن کامنت نوشته شده است. با بررسی نحوه نوشتن کامنت در این برنامه، مطابقت تورفتگی‌ها را متوجه می‌شویم.
...
# Define again() function to ask user if they want to use the calculator again
def again():
# Take input from user
calc_again = input('''
Do you want to calculate again?
Please type Y for YES or N for NO.
''')
# If user types Y, run the calculate() function
if calc_again == 'Y':
calculate()
# If user types N, say good-bye to the user and end the program
elif calc_again == 'N':
print('See you later.')
# If user types another key, run the function again
else:
again()
کامنت‌ها برای کمک به برنامه‌نویسان ساخته شده‌اند؛ چه آنها برنامه‌نویس اصلی باشند یا اینکه بعد بخواهند در پروژه همکاری کنند. اگر کامنتی نتواند به شکلی مناسب نگهداری و سپس با کد پایه بروزرسانی شود، بهتر از ابتدا نوشته نشود. بنابراین، از نوشتن کامنت‌های مبهم و یا متناقض با کد اصلی جداً خودداری کنید.
در هنگام نوشتن کامنت، باستی به دنبال چرایی و هدف از آوردن خطوط مختلف کد برنامه باشیم. در صورتی که کد تخصصی و فنی نباشد، بایستی با نگاه به کد بتوان تشخیص داد که عملکرد و نحوه کاربری آن چگونه است.
کامنت‌های بلوکی
کامنت‌های بلوکی برای توضیح بیشتر کدهای پیچیده یا کدهایی که مخاطبان چندان با آنها آشنا نیستند۷، به کار می‌روند. این کامنت‌ها با فرمت طولانی‌تر برای بخش یا کل کد برنامه استفاده می‌شوند و میزان تورفتگی آنها مطابق با کد است.
در کامنت‌های بلوکی، هر کدام از خطوط با علامت هشتگ و یک فاصله خالی شروع می‌شود. در صورتی که بخواهید از بش از یک پاراگراف برای این منظور استفاده کنید، بایستی آنها را با یک خط که تنها دارای یک علامت هشتگ است، از یکدیگر جدا نمایید.
در اینجا نمونه‌ای از یک کامنت بلوکی که عملکرد تابع main() را تعریف می‌کند، مشاهده می‌کنید.
# The main function will parse arguments via the parser variable. These # arguments will be defined by the user on the console. This will pass # the word argument the user wants to parse along with the filename the # user wants to use, and also provide help text if the user does not # correctly pass the arguments. def main(): parser = argparse.ArgumentParser() parser.add_argument( "word", help="the word to be searched for in the text file." ) parser.add_argument( "filename", help="the path to the text file to be searched through" ) ...
کامنت‌های بلوکی معمولاً زمانی استفاده می‌شوند که عملگرها چندان شفاف نیستند و بنابراین، نیاز به توضیحات بیشتر دارند. در همین حال، باید از ارائه توضیحات بیش از حد در برنامه پرهیز کنید. ضمن اینکه به برنامه‌نویسان دیگر در زمینه درک پایتون، اطمینان کافی داشته باشید؛ مگر اینکه مخاطب خاص دیگری مدّنظر شما باشد.
نوشتن کامنت درون‌خطی
کامنت‌های درون‌خطی در همان خط و بعد از کد نوشته می‌شوند. همانند دیگر انواع کامنت‌ها، آنها نیز با علامت هشتگ و یک خط فاصله شروع می‌شوند.
به طور کلی، کامنت‌های درون‌خطی ظاهری شبیه به زیر دارند.
# Inline comment about the code
کامنت‌های درون‌خطی بهتر است به صورت جداگانه باشند. در همین حال، می‌توانند برای توضیح بخش‌های تخصصی یا غیرواضح بسیار مفید واقع شوند. همچنین اگر فکر می‌کنید که در آینده ممکن است برخی خطوط برنامه را فراموش کنید و یا با شخصی همکاری می‌کنید که با تمام جنبه‌های کد آشنا نیست، این نوع کامنت‌ها به کار شما می‌آیند.
به عنوان نمونه، اگر زیاد از ریاضیات در برنامه‌های پایتون استفاده نمی‌کنید، احتمالاً شما یا همکارانتان از تشکیل عدد مختلط توسط کد زیر اطلاع ندارید. بر این اساس، احتمالاً نیاز به یک کامنت درون‌خطی به صورت زیر پیدا می‌کنید.
z = 2.5 + 3j # Create a complex number
نوشتن کامنت درون‌خطی می‌تواند به منظور ارائه توضیح یک عملکرد یا برخی توضیحات اضافه نیز صورت گیرد.
x = 8 # Initialize x with an arbitrary number
کامنت‌های درون‌خطی بایستی فقط در هنگام ضرورت و زمانی که بتوانند راهنمایی مفیدتری در اختیار خواننده قرار دهند، نوشته شوند.
کامنت‌کردن کد برای آزمایش برنامه
علاوه بر نوشتن کامنت به منظور مستندسازی کد، علامت هشتگ می‌تواند برای کامنت‌کردن بخش‌هایی از کد مورد استفاده قرار گیرد. هدف از این کامنت‌کردن، جلوگیری از اجرای بخش‌هایی از کد در زمان آزمایش یا عیب‌یابی برنامه است. وقتی بعد از بکارگیری خطوط کد جدید، متوجه پیغام خطا می‌شوید، ممکن است بخواهید برخی از آنها را کامنت کنید تا ببنید که مشکل دقیقاً از کدام قسمت برنامه است.
همچنین استفاده از کامنت‌ها می‌تواند راه‌حل‌های جایگزین شما را در بر داشته باشد. به عنوان مثال، در صورتی که بخواهید برای نوشتن یک بازی پایتون، بین استفاده از حلقه‌های while یا for تصمیم‌گیری کنید، می‌توانید با کامنت‌کردن هر یک از این راه‌حل‌ها را آزمایش کنید.
import random
number = random.randint(1, 25)
# number_of_guesses = 0
for i in range(5):
# while number_of_guesses < 5:
print('Guess a number between 1 and 25:')
guess = input()
guess = int(guess)
# number_of_guesses = number_of_guesses + 1
if guess < number:
print('Your guess is too low')
if guess > number:
print('Your guess is too high')
if guess == number:
break
if guess == number:
print('You guessed the number!')
else:
print('You did not guess the number. The number was ' + str(number))
کامنت‌کردن کد با استفاده از علامت هشتگ موجب می‌شود که بتوانید راه‌های مختلف برنامه‌نویسی را امتحان کنید و همین طور منبع خطا را در بخش‌های مختلف برنامه شناسایی نمایید.
جمع‌بندی
نوشتن کامنت درون برنامه‌های پایتون به شما کمک می‌کند که برنامه‌هایی خواناتر بنویسید. در نتیجه، برنامه‌نویسان یا خودِ شما در آینده بهتر می‌توانید با کد برنامه ارتباط برقرار کنید. ارائه کامنت‌های مفید می‌تواند شرایط را برای همکاری دیگران در پروژه و ارتقای ارزش کدهای شما تسهیل کند.