آموزش پایتون از صفر تا … (قسمت۲) – کامنت

با نام خدا و سلام. تو این قسمت میخوام به طور کامل در مورد کامنت گذاری در پایتون براتون بنویسم. امیدوارم مفید باشه 🙂

کامنت مثل تابلو راهنما می مونه که به کدی که نوشته شده خود آشکاری و خوانایی بالایی می دهد. تو پایتون ما دو نوع کامنت تک خط و چند خط داریم. تو این قسمت از آموزش سعی شده هر جفت کامنت ها پوشش داده بشه.

کامنت گذاری به نظر من یه بحث مهمی از کد زنی محسوب میشه، شما با کامنت گذاری کار خودتون رو معرفی می کنید و به دیگرتوسعه دهندگانی که از کدتون استفاده می کنند این امکان رو می دهید که کد رو خیلی ساده تر متوجه شده و به توسعه بهتر کد کمک کنند.

توسعه دهندگان خوب، همواره به کامنت گذاری توجه زیادی دارند و خوبه که همه توسعه دهندگان به این مهم توجه کنند. مخصوصا هنگامی که برنامه ای که دارید توسعه می دهید در حال بزرگ شدنه و پیچیدگی هاش نیز بیشتر میشه و در نتیجه خوانایی و نگهداریش نیز سخت تر میشه.

خود کد فقط میتونه به شما بگه که چطوری انجام میده، ولی نمیتونه بگه که چرا انجام میده!

کامنت در پایتون با یک هش مارک (#) و فاصله (whitespace) شروع میشه، کامنت چیزی مثل این خواهد بود:

# This is a comment

کامنت بالایی ، کامنت تک خط نامیده میشه، برای مواقعی که نیاز به اطلاعات کمی برای هر نوشته داشته باشید به کار میاد. آخر هر کامنت تک خط، به صورت خودکار یک EOL گذاشته می شود.

# Good code is self-documenting.

print("Learn Python Step by Step in sadegh-khan.ir ")

وقتی که دارید کامنت گذاری می کنید مطمین بشید که کامنت شما فرورفتگی یکسانی با کدی که در زیر آن است داشته باشد.

اما یک تابع میتونه تکه کدهایی با فرورفتگی های مختلف داشته باشد. بنابراین زمانی که دارید داخل یک تکه کد درون تابع کامنت می گذارید، مراقب تراز باشید.

# Define a list of months
months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul','Aug','Sep','Oct','Nov','Dec']

# Function to print the calender months
def showCalender(months):
    # For loop that traverses the list and prints the name of each month
    for month in months:
        print(month)

showCalender(months)

نکته: کامنت برای کمک به برنامه نویس ها استفاده میشه، چه برنامه نویس اصلی یه برنامه و چه دیگر برنامه نویس ها که برای توسعه یا نگهداری از کد با اون کار می کنند. اگر کامنت به خوبی نگهداری نشه و بر مبنای که بروز نشه، بهتر است که کامنت گذاری انجام نشه تا اینکه یه کامنتی استفاده بشه که با کد تناقض داشته باشه.

کامنت گذاری برای چند خط

پایتون به کامنت اجازه میده که در چند خط span بشه . از این روش کامنت گذاری برای کامنت هایی که پیچیدگی بیشتری دارند استفاده می شود.

برای کامنت گذاری در چند خط، شما باید هر خط را با یک (#) و یک فاصله بعدش شروع کنید. بین هر دو پاراگراف نیز می توانید یک (#) و فاصله اضافی بعدش، بین دو پاراگراف بگذارید.

# To Learn any language you must follow the below rules.
# 1. Know the basic syntax, data types, control structures and conditional statements.
# 2. Learn error handling and file I/O.
# 3. Read about advanced data structures.
# 4. Write functions and follow OOPs concepts.

def main():
    print("Let's start to learn Python.")
...

نکته: اگرکامنت در همان خطی که دستور (کد) هست، قرار بگیره بهش میگیم inline comment ، مانند تکه کد زیر:

salary = salary * 1.02   # increase salary 2% for the employee

Docstring در پایتون

پایتون دارای ویژگی documentation strings یا docstrings می باشد. این ویژگی به برنامه نویسان روش آسانی را برای اضافه کردن quick notes به هر ماژول، تابع، کلاس و متد می دهد.

docstrings  باید در ابتدای تعریف ماژول، تابع، کلاس یا متد باشد. docstrings محدوده ی وسیعتری نسبت به کامنت دارد. از این جهت که باید توضیح بده که تابع چه انجام می دهد نه این که چطور انجام می دهد.

چطور Docstring را در پایتون تعریف کنیم؟

شما می توانید Docstring را با کمک triple-quotation اعریف کنید. یکی ابتدا و دومی در انتهای string مورد نظر. همانند کامنت چند خطی، Docstring نیز می تواند چند خط را در بر بگیرد.

نکته: متنی که توسط triple-quotation تعریف می شود در پایتون Docstring نامیده می شود. گرچه ممکن است مانند کامنت معمولی به نظر آید.

اما تفاوت بین Docstring و کامنت در چیست؟

متنی که با triple-quotation آغاز می شودهمانند یک string معمول می باشد جز اینکه که می تواند بین چند خط پراکندگی داشته باشد. به این معنی که دستورات قابل اجرا هستند. و اگر برچسب گذاری نشوند (label)، سپس در هنگام اجرای کد به عنوان garbage جمع آوری می شوند.

مفسر پایتون اون ها را همانند کامنت کنار نمیگذارد. شما با دستور زیر می توانید به Docstring دسترسی داشه باشید:

myobj.__doc__

مثال:

def theFunction():
    '''
This function demonstrate the use of docstring in Python.
    '''
    print("Python docstrings are not comments.")

print("\nJust printing the docstring value...")
print(theFunction.__doc__)

خروجی دستورات فوق:

نکته آخر :

یک نرم افزار تنها ۱۰درصد از عمر خودش را در توسعه (development) می گذراند، و ۹۰درصد عمرش در هنگام نگهداری (maintenance) سپری می شود.

آموزش ها از قرار زیر هستند (در حال تکمیل) : 

• آموزش پایتون از صفر تا … (مقدمه)

• آموزش پایتون از صفر تا … (قسمت۱) کلیدواژه، شناسه و متغیر ها

• آموزش پایتون از صفر تا … (قسمت۲) – کامنت

• آموزش پایتون از صفر تا … (قسمت ۳) – String

• آموزش پایتون از صفر تا … (قسمت ۴) – ادامه String