KAHIBARO Bookshelves
Discord Login Register

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

چرا به کامنت نیاز داریم؟

وقتی کد می‌نویسید، فقط کامپیوتر قرار نیست آن را «بفهمد»؛ خودِ شما (در آینده) و بقیه برنامه‌نویس‌ها هم باید بفهمند این کد چه کار می‌کند.
کامنت‌ها (comments) بخش‌هایی از کد هستند که پایتون آن‌ها را اجرا نمی‌کند و فقط برای انسان‌ها نوشته می‌شوند تا:

  • توضیح بدهند کد چه کاری انجام می‌دهد.
  • دلیل یک تصمیم یا راه‌حل را روشن کنند.
  • یادداشت‌هایی برای آینده بگذارند (برای خودتان یا دیگران).
  • بخش‌هایی از کد را موقتاً «غیرفعال» کنند.

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

در پایتون کامنت‌ها دو نوع اصلی دارند:

  1. کامنت تک‌خطی (رایج‌ترین نوع)
  2. کامنت چندخطی (برای توضیحات طولانی)

کامنت تک‌خطی با `#`

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

مثال ساده:

# این یک کامنت است و اجرا نمی‌شود
print("سلام")  # این هم یک کامنت بعد از کد است

در این مثال:

  • خط اول: فقط کامنت است.
  • خط دوم: بخش print("سلام") اجرا می‌شود، اما بخش بعد از # نادیده گرفته می‌شود.

محل قرار گرفتن `#`

  • می‌تواند در ابتدای خط باشد:
  # محاسبهٔ مساحت مستطیل
  area = 5 * 3
  • می‌تواند بعد از یک دستور در همان خط باشد:
  area = 5 * 3  # طول در عرض

نکتهٔ مهم: هر چیزی بعد از # تا انتهای همان خط، کامنت است؛ بنابراین:

print("سلام # دنیا")  # این # داخل رشته است نه کامنت

در اینجا # داخل رشته ("سلام # دنیا") است و بخشی از متن چاپ‌شده محسوب می‌شود، نه کامنت.

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

در پایتون علامت خاصی مثل / ... / (در بعضی زبان‌ها) برای کامنت چندخطی وجود ندارد، اما می‌توانیم چند خط پشت‌سر هم کامنت تک‌خطی بنویسیم:

# این برنامه میانگین سه عدد را حساب می‌کند
# ابتدا مجموع سه عدد را پیدا می‌کنیم
# سپس آن را بر ۳ تقسیم می‌کنیم
sum_numbers = 10 + 20 + 30
average = sum_numbers / 3

این روش رایج‌ترین و خواناترین روش نوشتن کامنت‌های چندخطی است.

رشته‌های سه‌گانه و «کامنت چندخطی»

شاید ببینید کسی از رشته‌های سه‌گانه (""" ... """ یا ''' ... ''') برای نوشتن یک متن توضیحی چندخطی استفاده می‌کند:

"""
این بخش از کد برای محاسبهٔ سود
در یک سرمایه‌گذاری ساده است
"""
profit = 100000 * 0.2

اگر این رشته در جایی استفاده نشود (به متغیر نسبت داده نشود یا به‌عنوان مقدار بازگشتی برنگردد)، عملاً در زمان اجرا نادیده گرفته می‌شود.
اما نکتهٔ مهم:

  • از نظر فنی این کامنت نیست، بلکه یک رشتهٔ بدون استفاده است.
  • در عمل خیلی‌ها برای توضیح‌های طولانی از این روش استفاده می‌کنند، اما برای شروع بهتر است برای توضیحات عادی از # استفاده کنید.

چه چیزهایی را کامنت کنیم؟

هدف این نیست که «همه چیز» را کامنت کنید. چند قانون ساده:

۱. توضیح «چرا» نه فقط «چه»

گاهی کد خودش می‌گوید «چه کاری» انجام می‌دهد، اما معلوم نیست «چرا این روش» را انتخاب کرده‌اید.

# اگر کاربر سه بار پشت سر هم اشتباه وارد کند، حسابش موقتاً قفل می‌شود
max_wrong_attempts = 3

این کامنت توضیح می‌دهد هدف این عدد ۳ چیست.

۲. واضح را دوباره نگویید

این کامنت‌ها کمکی نمی‌کنند:

x = 5        # مقدار x را 5 می‌کنیم
print(x)     # چاپ x

چیزی را که از روی کد کاملاً واضح است، دوباره ننویسید.
کامنت باید به درک بهتر کمک کند، نه فقط تکرار همان چیزی که در کد دیده می‌شود.

۳. خلاصه در ابتدای یک بخش

اگر چند خط کد با هم یک کار مشخص انجام می‌دهند، می‌توانید قبل از آن‌ها یک کامنت کوتاه بگذارید و هدف آن بخش را توضیح دهید:

# محاسبهٔ هزینهٔ کل سفارش با احتساب مالیات
price = 200000
tax = price * 0.09
total = price + tax

استفاده از کامنت برای غیرفعال کردن موقت کد

گاهی می‌خواهید یک خط یا چند خط کد را موقتاً اجرا نکنید تا تستی انجام دهید. یکی از راه‌های ساده، تبدیل آن خط‌ها به کامنت است:

#print("این خط فعلاً اجرا نمی‌شود")
print("فقط این خط اجرا می‌شود")

یا برای چند خط:

#print("مرحله ۱")
#print("مرحله ۲")
print("فقط مرحله ۳ فعلاً لازم است")

یادتان باشد بعد از اتمام تست، اگر آن کد لازم است، # را پاک کنید تا دوباره اجرا شود.

سبک نوشتن و نکات عملی

چند نکتهٔ کوچک اما مهم:

فاصله بعد از `#`

مرسوم است بعد از # یک فاصله بگذاریم تا خواناتر باشد:

  • بهتر: # محاسبهٔ جمع
  • نه‌چندان خوب: #محاسبهٔ جمع
total = 10 + 20  # جمع دو عدد

زبان کامنت

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

نکتهٔ مهم: سعی کنید کامنت‌ها ساده و قابل‌فهم باشند، نه جمله‌های طولانی و مبهم.

به‌روز نگه داشتن کامنت‌ها

اگر کد را تغییر دادید، ولی کامنت را نه، ممکن است کامنت دروغ بگوید! این خیلی خطرناک است.

مثلاً:

# محاسبهٔ مساحت مربع
area = length * width

اگر بعداً تصمیم گرفتید اینجا مساحت مستطیل حساب کنید (و دیگر مربع نیست)، باید کامنت را هم اصلاح کنید:

# محاسبهٔ مساحت مستطیل
area = length * width

همیشه بعد از تغییر کد، نگاهی به کامنت‌های اطرافش بیندازید.

چند مثال کاربردی

مثال ۱: توضیح هدف برنامه

# این برنامه، سن کاربر را از او می‌گیرد و سال تولد تقریبی‌اش را حساب می‌کند
age = int(input("سن شما چند سال است؟ "))
current_year = 2024
birth_year = current_year - age
print("احتمالاً سال تولد شما", birth_year, "است.")

کامنت ابتدای برنامه خیلی سریع می‌گوید این کد چه کاری انجام می‌دهد.

مثال ۲: توضیح یک قسمت سخت‌تر

number = 17
# اگر عدد فرد است، یکی از آن کم می‌کنیم تا زوج شود،
# چون الگوریتم ما فقط با اعداد زوج کار می‌کند.
if number % 2 == 1:
    number = number - 1
print(number)

اینجا بدون کامنت ممکن است ندانیم «چرا» عدد فرد را یک واحد کم می‌کنیم.

مثال ۳: استفادهٔ هم‌زمان از چند نوع کامنت

# محاسبهٔ نمرهٔ نهایی دانش‌آموز
mid = 15      # نمرهٔ میان‌ترم
final = 18    # نمرهٔ پایان‌ترم
project = 17  # نمرهٔ پروژه
# وزن‌دهی به نمره‌ها:
# میان‌ترم 30 درصد، پایان‌ترم 50 درصد، پروژه 20 درصد
total_score = mid * 0.3 + final * 0.5 + project * 0.2
print("نمرهٔ نهایی:", total_score)

در این مثال:

  • یک کامنت کلی در ابتدای برنامه است.
  • کامنت‌های کوتاه کنار متغیرهاست.
  • یک توضیح چندخطی در مورد فرمول وزن‌دهی داریم.

جمع‌بندی

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

Views: 0

Comments

Please login to add a comment.

Don't have an account? Register now!

Where to Move

Move chapter:

  • ☰ 1. فصل ۱: برنامه‌نویسی چیست؟
    • ☰ 1.1. برنامهٔ کامپیوتری چیست؟
      • ☰ 1.2. پایتون چیست؟
        • ☰ 1.3. پایتون کجا استفاده می‌شود؟
          • ☰ 1.4. چگونه برنامه‌نویسی به حل مسائل کمک می‌کند
            • ☰ 1.5. اولین برنامهٔ پایتون شما
            • ☰ 2. فصل ۲: راه‌اندازی پایتون
              • ☰ 2.1. نصب پایتون (ویندوز / macOS / لینوکس)
                • ☰ 2.2. استفاده از پایتون در ترمینال
                  • ☰ 2.3. استفاده از یک IDE (IDLE / VS Code)
                    • ☰ 2.4. اجرای اسکریپت‌های پایتون
                      • ☰ 2.5. حالت تعاملی پایتون
                      • ☰ 3. فصل ۳: متغیرها و انواع داده
                        • ☰ 3.1. متغیر چیست؟
                          • ☰ 3.2. ایجاد متغیرها
                            • ☰ 3.3. اعداد (`int`، `float`)
                              • ☰ 3.4. متن (`str`)
                                • ☰ 3.5. مقادیر بولی (`True`، `False`)
                                  • ☰ 3.6. بررسی نوع داده با `type()`
                                  • ☰ 4. فصل ۴: عملیات پایه
                                    • ☰ 4.1. عملیات حسابی
                                      • ☰ 4.2. کار با اعداد
                                        • ☰ 4.3. عملیات روی رشته‌ها
                                          • ☰ 4.4. ترکیب متن و متغیرها
                                            • ☰ 4.5. کامنت‌ها در پایتون
                                            • ☰ 5. فصل ۵: ورودی و خروجی کاربر
                                              • ☰ 5.1. دریافت ورودی از کاربر
                                                • ☰ 5.2. تبدیل ورودی به عدد
                                                  • ☰ 5.3. قالب‌بندی خروجی
                                                    • ☰ 5.4. نوشتن برنامه‌های تعاملی
                                                    • ☰ 6. فصل ۶: شرط‌ها (if / else)
                                                      • ☰ 6.1. عملگرهای مقایسه‌ای
                                                        • ☰ 6.2. عملگرهای منطقی
                                                          • ☰ 6.3. if، elif، else
                                                            • ☰ 6.4. شرط‌های تو در تو
                                                              • ☰ 6.5. اشتباهات رایج مبتدیان
                                                              • ☰ 7. فصل ۷: حلقه‌ها
                                                                • ☰ 7.1. چرا حلقه‌ها مفید هستند؟
                                                                  • ☰ 7.2. حلقه‌های while
                                                                    • ☰ 7.3. حلقه‌های for
                                                                      • ☰ 7.4. شمارنده‌های حلقه
                                                                        • ☰ 7.5. break و continue
                                                                          • ☰ 7.6. تمرین‌های حلقه
                                                                          • ☰ 8. فصل ۸: مجموعه‌های داده
                                                                            • ☰ 8.1. لیست‌ها (Lists)
                                                                              • ☰ 8.2. تاپل‌ها (Tuples)
                                                                                • ☰ 8.3. دیکشنری‌ها (Dictionaries)
                                                                                  • ☰ 8.4. مجموعه‌ها (Sets – مقدماتی)
                                                                                    • ☰ 8.5. انتخاب ساختار دادهٔ مناسب
                                                                                    • ☰ 9. فصل ۹: توابع
                                                                                      • ☰ 9.1. چرا توابع مهم هستند؟
                                                                                        • ☰ 9.2. تعریف توابع
                                                                                          • ☰ 9.3. پارامترها و آرگومان‌ها
                                                                                            • ☰ 9.4. مقادیر بازگشتی
                                                                                              • ☰ 9.5. محدودهٔ متغیرها (محلی در برابر سراسری)
                                                                                                • ☰ 9.6. استفادهٔ مجدد از کد
                                                                                                • ☰ 10. فصل ۱۰: کار با فایل‌ها
                                                                                                  • ☰ 10.1. فایل چیست؟
                                                                                                    • ☰ 10.2. خواندن فایل‌های متنی
                                                                                                      • ☰ 10.3. نوشتن و افزودن به فایل‌ها
                                                                                                        • ☰ 10.4. مسیر فایل‌ها
                                                                                                          • ☰ 10.5. برنامه‌های ساده مبتنی بر فایل
                                                                                                          • ☰ 11. فصل ۱۱: خطاها و اشکال‌زدایی
                                                                                                            • ☰ 11.1. انواع خطاها
                                                                                                              • ☰ 11.2. خواندن پیام‌های خطا
                                                                                                                • ☰ 11.3. خطاهای رایج مبتدیان
                                                                                                                  • ☰ 11.4. try و except
                                                                                                                    • ☰ 11.5. راهبردهای اشکال‌زدایی
                                                                                                                    • ☰ 12. فصل ۱۲: استفاده از کتابخانه‌های پایتون
                                                                                                                      • ☰ 12.1. کتابخانه چیست؟
                                                                                                                        • ☰ 12.2. وارد کردن ماژول‌ها
                                                                                                                          • ☰ 12.3. کتابخانه‌های استاندارد
                                                                                                                            • ☰ 12.3.1. math
                                                                                                                              • ☰ 12.3.2. random
                                                                                                                                • ☰ 12.3.3. datetime
                                                                                                                                • ☰ 12.4. نصب کتابخانه‌های خارجی با pip
                                                                                                                                • ☰ 13. فصل ۱۳: برنامه‌نویسی شی‌گرا (OOP)
                                                                                                                                  • ☰ 13.1. برنامه‌نویسی شی‌گرا چیست؟
                                                                                                                                    • ☰ 13.2. کلاس‌ها و اشیاء
                                                                                                                                      • ☰ 13.3. ویژگی‌ها و متدها
                                                                                                                                        • ☰ 13.4. متد `__init__`
                                                                                                                                          • ☰ 13.5. کپسوله‌سازی
                                                                                                                                            • ☰ 13.6. وراثت (مقدماتی)
                                                                                                                                              • ☰ 13.7. مثال‌های سادهٔ شی‌گرا
                                                                                                                                              • ☰ 14. فصل ۱۴: خودکارسازی با پایتون
                                                                                                                                                • ☰ 14.1. خودکارسازی چیست؟
                                                                                                                                                  • ☰ 14.2. خودکار کردن وظایف ساده
                                                                                                                                                    • ☰ 14.3. کار با فایل‌ها و پوشه‌ها
                                                                                                                                                      • ☰ 14.4. خودکارسازی پردازش متن
                                                                                                                                                        • ☰ 14.5. زمان‌بندی اجرای اسکریپت‌ها
                                                                                                                                                          • ☰ 14.6. مثال‌های کاربردی خودکارسازی
                                                                                                                                                          • ☰ 15. فصل ۱۵: توسعهٔ وب با پایتون
                                                                                                                                                            • ☰ 15.1. وب چگونه کار می‌کند؟ (نمای کلی)
                                                                                                                                                              • ☰ 15.2. آشنایی با Flask
                                                                                                                                                                • ☰ 15.3. ساخت یک وب‌سرور ساده
                                                                                                                                                                  • ☰ 15.4. مسیرها و قالب‌ها (Templates)
                                                                                                                                                                    • ☰ 15.5. پردازش ورودی کاربر (فرم‌ها)
                                                                                                                                                                      • ☰ 15.6. API های بسیار ساده
                                                                                                                                                                      • ☰ 16. فصل ۱۶: علم داده با پایتون
                                                                                                                                                                        • ☰ 16.1. علم داده چیست؟
                                                                                                                                                                          • ☰ 16.2. کار با داده‌ها
                                                                                                                                                                            • ☰ 16.3. آشنایی با NumPy
                                                                                                                                                                              • ☰ 16.4. آشنایی با pandas
                                                                                                                                                                                • ☰ 16.5. مصورسازی داده با matplotlib
                                                                                                                                                                                  • ☰ 16.6. مثال‌های سادهٔ تحلیل داده
                                                                                                                                                                                  • ☰ 17. فصل ۱۷: پروژه‌های کوچک
                                                                                                                                                                                    • ☰ 17.1. بازی حدس عدد
                                                                                                                                                                                      • ☰ 17.2. ماشین‌حساب ساده
                                                                                                                                                                                        • ☰ 17.3. فهرست کارها (To-Do List)
                                                                                                                                                                                          • ☰ 17.4. تولیدکنندهٔ رمز عبور
                                                                                                                                                                                            • ☰ 17.5. برنامهٔ آزمون (Quiz)
                                                                                                                                                                                              • ☰ 17.6. پروژهٔ کوچک وب یا داده
                                                                                                                                                                                              • ☰ 18. فصل ۱۸: گام‌های بعدی
                                                                                                                                                                                                • ☰ 18.1. چگونه پایتون را تمرین کنیم
                                                                                                                                                                                                  • ☰ 18.2. نوشتن کد تمیز و خوانا
                                                                                                                                                                                                    • ☰ 18.3. انتخاب یک حوزهٔ تخصصی
                                                                                                                                                                                                      • ☰ 18.3.1. توسعهٔ وب
                                                                                                                                                                                                        • ☰ 18.3.2. علم داده
                                                                                                                                                                                                          • ☰ 18.3.3. خودکارسازی
                                                                                                                                                                                                            • ☰ 18.3.4. توسعهٔ نرم‌افزار
                                                                                                                                                                                                            • ☰ 18.4. منابع یادگیری و انجمن‌ها
                                                                                                                                                                                                            • ☰ 19. پیوست
                                                                                                                                                                                                              • ☰ 19.1. برگهٔ تقلب دستور زبان پایتون
                                                                                                                                                                                                                • ☰ 19.2. خطاهای رایج و راه‌حل‌ها
                                                                                                                                                                                                                  • ☰ 19.3. واژه‌نامهٔ اصطلاحات