التعليقات في بايثون (Python Comments)

# هذا تعليق في سطر مستقل
# المفسر سيتجاهل هذا السطر تماماً

print("Hello World")  # هذا تعليق في نهاية سطر كود

# يمكنك كتابة عدة تعليقات متتالية
# كل سطر يبدأ بـ #
# لشرح فكرة معقدة

x = 10  # تخزين الرقم 10 في المتغير x
y = 20  # تخزين الرقم 20 في المتغير y
result = x + y  # جمع x و y وحفظ النتيجة
print(result)  # طباعة النتيجة

# ✅ جيد: مسافة بعد #
#❌ سيء: لا مسافة بعد #

x = 5  # ✅ جيد: مسافتان قبل #
y = 10# ❌ سيء: لا مسافة قبل #

# ✅ جيد: تعليق واضح ومفيد
# نحسب مساحة المستطيل بضرب الطول في العرض
area = length * width

# ❌ سيء: تعليق واضح من الكود نفسه (غير ضروري)
x = 5  # تعيين 5 للمتغير x

# هذا برنامج لحساب مساحة الدائرة
# يطلب من المستخدم إدخال نصف القطر
# ثم يحسب المساحة باستخدام الصيغة: π × r²
# ويعرض النتيجة بدقة منزلتين عشريتين

import math

radius = float(input("أدخل نصف القطر: "))
area = math.pi * radius ** 2
print(f"مساحة الدائرة: {area:.2f}")

"""
هذا تعليق متعدد الأسطر باستخدام النصوص الثلاثية.
يمكنك كتابة عدة أسطر دون الحاجة لوضع # في كل سطر.
هذه الطريقة مفيدة للتعليقات الطويلة أو التوثيق.
"""

print("البرنامج يعمل")

'''
يمكنك أيضاً استخدام علامات التنصيص المفردة الثلاثية.
النتيجة نفسها تماماً.
اختر الطريقة التي تفضلها.
'''

print("انتهى البرنامج")

def calculate_area(length, width):
    """
    تحسب مساحة المستطيل.
    
    المعطيات:
        length (float): طول المستطيل
        width (float): عرض المستطيل
    
    القيمة المرجعة:
        float: مساحة المستطيل (طول × عرض)
    
    مثال:
        >>> calculate_area(5, 3)
        15
    """
    return length * width

# استخدام الدالة
result = calculate_area(10, 5)
print(f"المساحة: {result}")

# الوصول إلى الـ Docstring
print("\nتوثيق الدالة:")
print(calculate_area.__doc__)

# Docstring أحادي السطر (للدوال البسيطة)
def greet(name):
    """تطبع رسالة ترحيب بالاسم المعطى."""
    print(f"مرحباً {name}!")

# Docstring متعدد الأسطر (للدوال المعقدة)
def calculate_bmi(weight, height):
    """
    تحسب مؤشر كتلة الجسم (BMI).
    
    مؤشر كتلة الجسم يُحسب بقسمة الوزن (بالكيلوغرام)
    على مربع الطول (بالمتر).
    
    المعطيات:
        weight (float): الوزن بالكيلوغرام
        height (float): الطول بالمتر
    
    القيمة المرجعة:
        float: مؤشر كتلة الجسم
    
    استثناءات:
        ValueError: إذا كان الطول صفراً أو سالباً
    """
    if height <= 0:
        raise ValueError("الطول يجب أن يكون أكبر من صفر")
    
    return weight / (height ** 2)

# استخدام الدوال
greet("أحمد")
bmi = calculate_bmi(70, 1.75)
print(f"مؤشر كتلة الجسم: {bmi:.2f}")

print("هذا السطر سيُنفذ")

# print("هذا السطر معطّل مؤقتاً")
# print("وهذا أيضاً معطّل")

print("هذا السطر سيُنفذ أيضاً")

# أحياناً تريد تجربة طريقتين مختلفتين
# الطريقة القديمة (معطّلة):
# result = x * 2 + 5

# الطريقة الجديدة (نشطة):
result = (x + 1) * 2

print(result)

# ❌ تعليق سيء: يكرر ما يقوله الكود
x = 5  # تعيين 5 للمتغير x

# ✅ تعليق جيد: يشرح السبب
x = 5  # نستخدم 5 كقيمة افتراضية حسب متطلبات العميل

# ❌ تعليق سيء: واضح من الكود
# طباعة رسالة ترحيب
print("مرحباً")

# ✅ تعليق جيد: يشرح سياق غير واضح
# نطبع الرسالة بالعربية لأن المستخدمين المستهدفين عرب
print("مرحباً")

# ❌ تعليق سيء: مضلل (الكود يجمع لكن التعليق يقول يطرح)
result = a + b  # طرح a من b

# ✅ تعليق جيد: دقيق ومفيد
# نجمع الضريبة (15%) إلى السعر الأساسي
total = price + (price * 0.15)

"""
برنامج تحويل درجات الحرارة
================================
يحول درجات الحرارة بين مقياس سيلسيوس وفهرنهايت.

المؤلف: أحمد محمد
التاريخ: 2026-01-21
الإصدار: 1.0
"""

def celsius_to_fahrenheit(celsius):
    """
    تحول درجة الحرارة من سيلسيوس إلى فهرنهايت.
    
    الصيغة المستخدمة: F = (C × 9/5) + 32
    
    المعطيات:
        celsius (float): درجة الحرارة بالسيلسيوس
    
    القيمة المرجعة:
        float: درجة الحرارة بالفهرنهايت
    """
    # نستخدم 9/5 بدلاً من 1.8 لوضوح الصيغة الرياضية
    return (celsius * 9/5) + 32


def fahrenheit_to_celsius(fahrenheit):
    """
    تحول درجة الحرارة من فهرنهايت إلى سيلسيوس.
    
    الصيغة المستخدمة: C = (F - 32) × 5/9
    
    المعطيات:
        fahrenheit (float): درجة الحرارة بالفهرنهايت
    
    القيمة المرجعة:
        float: درجة الحرارة بالسيلسيوس
    """
    return (fahrenheit - 32) * 5/9


# البرنامج الرئيسي
print("=" * 50)
print("      برنامج تحويل درجات الحرارة")
print("=" * 50)
print()

# عرض الخيارات للمستخدم
print("اختر نوع التحويل:")
print("1. من سيلسيوس إلى فهرنهايت")
print("2. من فهرنهايت إلى سيلسيوس")
print()

# الحصول على اختيار المستخدم
# نستخدم try-except لاحقاً للتعامل مع الإدخال الخاطئ
choice = input("أدخل اختيارك (1 أو 2): ")

if choice == "1":
    # تحويل من سيلسيوس إلى فهرنهايت
    celsius = float(input("أدخل درجة الحرارة بالسيلسيوس: "))
    fahrenheit = celsius_to_fahrenheit(celsius)
    
    # عرض النتيجة بدقة منزلة عشرية واحدة
    print(f"{celsius}°C = {fahrenheit:.1f}°F")
    
elif choice == "2":
    # تحويل من فهرنهايت إلى سيلسيوس
    fahrenheit = float(input("أدخل درجة الحرارة بالفهرنهايت: "))
    celsius = fahrenheit_to_celsius(fahrenheit)
    
    print(f"{fahrenheit}°F = {celsius:.1f}°C")
    
else:
    # المستخدم أدخل خياراً غير صحيح
    print("خيار غير صحيح! الرجاء اختيار 1 أو 2")

print()
print("=" * 50)
print("      شكراً لاستخدام البرنامج!")
print("=" * 50)