پایتون کلید ورود به دنیای هوش مصنوعی! (قسمت هفتم: کامنت و داکیومنت)

سلام رفقا

آموزش پایتون رو با همدیگه شروع کردیم اگر تازه می خواهید پایتون یاد بگیرید به لینک زیر برید :

آموزش پایتون قسمت اول

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

فرض کنید قراره یه کد بهتون بدن و بفمید چیه . خب اگر اون نفری که کد نوشته براتون توضیح هم بنویسه مسلما سریع تر می فهمید چه کار کرده. این قضیه در مورد کدهای خودتون هم صادقه یعنی فرض کنید اگر خودتون کد نوشتید بعدا بخواهید بفهمید چی نوشتید کافیه توضیحات خودتون رو بخونید.

سه حالت برای کامنت گذاشتن داریم :

کامنت گذاری تک خطی single-line comment:

# This is a single line comment in Python

خیلی ساده با علامت هشتگ می شه کامنت تک خطی گذاشت و زیرش برنامتون رو بنویسید.

کامنت گذاری درخط inline comment :

print("Hello World") # This line prints "Hello World"

اینم مثل قبلیه فقط جلوی عبارت پایتون قرار می گیره برای اینکه بگید این چیه.

کامنت گذاری چند خطی multiline comment :

به این صورت :

" " " 
This type of comment spans multiple lines.
These are mostly used for documentation of functions, classes and modules.
" " "

این کامنت گذاری چند خطی بیشتر برای توضیح کلاس ها توابع و ماژول ها به کار می ره. اگه یادتون رفته تابع و ماژول چیه اینجا رو بخونید. همون طور که دیدید این نوع کامنت گذاری با سه تا " یا با سه تا ' انجام می شه.

فرض کنید یک تابع درون یک ماژول نوشتید مثل :

def func():
    """This is a function that does nothing at all"""
        return

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

print(func.__doc__)
This is a function that does nothing at all

یا اینکه وقتی از دستور help استفاده می کنید

help(func)
Help on function func in module __main__:
func()
    This is a function that does nothing at all

این جوری هست که شما می تونید برای تابع هاتون help بنویسید.

دقت کنید که این کار فقط با کامنت گذاری چند خطی انجام میشه و با # کار نمی کنه. مثال زیر رو ببینید:

def greet(name, greeting="Hello"):
    # Print a greeting to the user `name`
    # Optional parameter `greeting` can change what they're greeted with.
    print("{} {}".format(greeting, name))
    
    
print(greet.__doc__)
None

help(greet)
    Help on function greet in module main:
    greet(name, greeting='Hello')

همونطور که تو مثال میشه دید برای این حالت که از # استفاده شده هیچی نمیاد!

استاندارد PEP 257

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

داکیومنت تک خطی :

این نوع داکیومنت برای تابع های ساده و کوتاه استفاده میشه و کل توضیح در یک خط قرار می گیره مثل :

def hello():
    """Say hello to your friends."""
    print("Hello my friends!")

توضیحات هم در انتها با یک نقطه پایان می یابد.

داکیومنت چند خطی :

def hello(name, language="en"):
    """Say hello to a person.
    
    Arguments:
    name: the name of the person
    language: the language in which the person should be greeted
    """
    print(greeting[language]+" "+name)

خط اول یک توضیح در مورد خود تابع می ده و خط های بعدی پارامترهای اون تابع رو مشخص می کنه.

توی این لینک می تونید این استاندارد رو بخونید.

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