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

 

 

مستندات PEP 8که گاهی اوقات PEP8 یا PEP-8 نوشته می شود شامل دستورالعمل ها و بهترین شیوه ها در مورد نحوه کدنویسی با زبان پایتون است. این مستندات در سال ۲۰۰۱ توسط سه نفر Guido van Rossum, Barry Warsaw و Nick Coghlan نوشته شده  و تمرکز اصلی این pep روی خوانایی و زیبایی کدهای Python میباشد که برنامه نویسان مینویسند.

عبارت PEP مخفف Python Enhancement Proposal است و شماره های مختلفی از آن وجود دارد. PEP در واقع مستنداتی  است که ویژگی های جدید  و کاربردهای آن برای زبان پایتون را معرفی میکند  و جنبه های مختلف زبان python را بررسی میکند.

در این مقاله قصد دارم درباره ی pep شماره ۸ صحبت کنم که مناسب افراد مبتدی تا متوسط در پایتون است.

بعد از خواندن این مقاله قادر خواهید بود : 

1. کدهایی به زبان پایتون بنویسید که مطابق با PEP 8 باشد.
2. استدلال های پشت آموزش های ارائه شده در  PEP 8 را درک کنید.
3. محیط توسعه خود را طوری تنظیم کنید که بتوانید کدهای پایتون خود را سازگار با PEP 8 را شروع کنید.

 

چرا ما به pep8 پایتون نیاز داریم ؟

در واقع pep-8 به این منظور خلق شده است که خوانایی کدهای پایتون را بالا ببرد ولی چرا خوانایی انقدر مهم است؟ چرا طبق zen پایتون نوشتن کدهایی با خوانایی بالا جزو اصول برنامه نویسی پایتون است؟

نقل قولی از خیدو فان روسوم ( خالق پایتون ) وجود دارد که میگه : کدهای برنامه نویسی بیشتر از آنکه نوشته شوند خوانده میشوند ! 

ممکن است چندین دقیقه یا حتی چندین روز صرف کنید تا کدی بنویسید تا احراز هویت کاربران انجام دهد وقتی که کد ار نوشتید و تمام شد دوباره نمی روید آنرا بنویسید اما حتما آنرا دوباره میخوانید.

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

اگر در زبان برنامه نویسی Python تازه کار هستید ممکن است یادآوری کارایی یک قطعه کد که چند روز یا چند هفته پیش نوشته اید دشوار باشد.اگر از PEP8 استفاده کنید شما میتوانید مطمعن شوید که نام گذاری متغیرهای شما صحیح است. شما مطمئن هستید که فضاهای خالی لازم را اضافه کردید پس خوانایی کدهای شما خوب است. شما همچنین برای کدهای خود کامنت گذاری صحیحی کرده اید. همه ی اینها نشان میدهد که کدهای شما استاندارد است و به یاد آوری مجدد آنها آسان است.

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

پیروی کردن از قواعد pep8 به استخدام شما هم کمک میکند چون کارفرمایانی که کدهای تمیز و سازماندهی شما را ببینند به حرفه ای بودن شما پی خواهند برد.

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

 

قراردادهای نام گذاری در زبان برنامه نویسی پایتون

سادگی بهتر از پیچیدگی است . 

وقتی شما برنامه نویسی پایتون میکنید باید برای خیلی چیزها نام انتخاب کنید : متغیرها ، کلاس ها ، توابع ، پکیج ها و ... .

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

همچنین از انتخاب نام های نامناسب که باعث بوجود آمدن error میشوند و دیباگ کردن آنها مشکل است خودداری کنید.

سسس

یک نکته : هرگز در برنامه نویسی از حروف l, O بصورت خالی برای اسم متغیر انتخاب نکنید چون شبیه عدد 0 و 1 هستند. مثال زیر را ببینید :‌

O = 2

شبیه اینه که شما عدد دو را درون صفر ریختید ! ولی در واقع متغیر o هست

 

استایل نامگذاری در پایتون

در جدول زیر برخی از سبک های نام گذاری رایج در زبان برنامه نویسی پایتون آمده و زمانی که باید از آنها استفاده کنیم نیز نشان داده شده است : 

 

 

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

 

در برنامه نویسی پایتون چطور اسم ها را انتخاب کنیم ؟ 

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

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

>>> # Not recommended
>>> x = 'John Smith'
>>> y, z = x.split()
>>> print(z, y, sep=', ')
'Smith, John'

نامگذاری به این شکل از نظر سینتکسی درست است و کار میکند ولی شما باید همیشه به یاد بیارید که متغیرهای x و y و z چه چیزی بودند.

همچنین تشابه اسم ها ممکن است گیج کننده باشد. مثال زیر نامگذاری بهتری است : 

>>> # Recommended
>>> name = 'John Smith'
>>> first_name, last_name = name.split()
>>> print(last_name, first_name, sep=', ')
'Smith, John'

 همچنین مختصر بودن نام ها باعث اشتباه در تشابه نامی میشود برای مثال در کد زیر یک تابع db تعریف کردیم که یک عدد را گرفته و دو برابر میکند :

# Not recommended
def db(x):
    return x * 2

در نگاه اول نام این تابع ممکن است عاقلانه به نظر برسد چون مخفف double هست ولی اگر چند روز به کدهای خود برگردید به یاد نمی آورید که db به معنی چیست ؟ آیا db همان database است یا double یا چی ؟

نام انتخاب شده در زیر بسیار مناسب تر است اگر شما روزهای بعد مراجعه کنید به راحتی میفهمید که این تابع برای کجاست و چه کاری انجام میدهد : 

# Recommended
def multiply_by_two(x):
    return x * 2

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

 

چیدمان صحیح کدها در پایتون

نحوه ی چیدمان کدها نقش مهمی در خوانایی کدهای یک برنامه نویس پایتون دارد.در این بخش یادمیگیرید چطور از فضاهای خالی عمودی برای بهبود خوانایی کد خود استفاده کنید و همچنین چطور محدودیت ۷۹ کاراکتری هر خط برنامه نویسی را طبق PEP 8 رعایت کنید.

 

خطوط خالی : 

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

در زیر سه دستورالعمل کلیدی درباره ی استفاده از خطوط سفید آورده ایم با ادامه مقاله همراه ما باشید : 

 

۱-  توابع و کلاس های top level یا مستقل را با دو خط خالی جدا کنید.

توابع و کلاس های top level ( مستقل یا سطح بالا ) باید نسبتاً مستقل از کدهای دیگر شما باشند چراکه هرکدام عملکردهای خاص خود را دارند. منطقی است که خطوط خالی اضافی در اطراف آنها قرار دهید، به طوری که مشخص شود که آنها از هم جدا هستند. بعد از تعریف هر کلاس یا تابع مستقل دو عدد خط خالی قرار دهید تا از بقیه خطوط پایتون جدا باشد . مثل زیر :‌

class MyFirstClass:
    pass


class MySecondClass:
    pass


def top_level_function():
    return None

 

۲- متودهای درون یک کلاس را با یک خط خالی از هم بقیه ی کدها جدا کنید.

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

class MyClass:
    def first_method(self):
        return None

    def second_method(self):
        return None

 

۳- درون توابع پایتون از خط خالی برای جداسازی قدم های مختلف استفاده کنید.

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

در مثال زیر یک تابع داریم که واریانس یک list را محاسبه میکند. عملیات درون این تابع در دو قدم انجام میشود پس من هر قدم را با یک فضای خالی یا خط خالی از هم جداسازی کردم و در نهایت یک خط خالی درست قبل از return قرار دادم که باعث میشود خواننده کاملا متوجه شود که چه چیزی خروجی تابع ما است :‌

def calculate_variance(number_list):
    sum_list = 0
    for number in number_list:
        sum_list = sum_list + number
    mean = sum_list / len(number_list)

    sum_squares = 0
    for number in number_list:
        sum_squares = sum_squares + number**2
    mean_squares = sum_squares / len(number_list)

    return mean_squares - mean**2

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

 

حداکثر طول هر خط در کدنویسی پایتون و شکستن خطوط کدها

اصول pep8 به ما پیشنهاد میکند که طول هر خط کد به زبان پایتون باید ۷۹ کاراکتر باشد. دلیل استفاده از ۷۹ کاراکتر در هر خط این است که شما میتوانید چند فایل را در کنار هم باز کنید و همچنین از بیرون زدگی خطوط کدنویسی جلوگیری میشود.

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

زبان برنامه نویسی پایتون هر خط را در خط پایینی ادامه میدهد در صورتی که عبارت درون پرانتز یا براکت یا آکولاد باشد. به مثال زیر دقت کنید :‌

def function(arg_one, arg_two,
             arg_three, arg_four):
    return arg_one

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

from mypkg import example1, \
    example2, example3

به هر حال اگر استفاده از پرانتز ، براکت یا آکولاد مقدور است حتما باید از انها استفاده کنید.

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

دو مثال زیر را بررسی کنید.

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

# Recommended
total = (first_variable
         + second_variable
         - third_variable)

در مثال بالا شما بلافاصله میبینید که روی متغیر چه عملگر اعمال شده است چون متغیر بلافاصله بعد از عملگر قرار گرفته است.

حالا اگر خطوط را بعد از عملگرها بشکنیم به شکل زیر میشود : 

# Not Recommended
total = (first_variable +
         second_variable -
         third_variable)

و اینجا خوانایی کدهای پایتون کمی بدتر میشود چون مشخص نیست که کدام متغیر جمع شده و کدام تفریق شده.

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

 

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

فضای خالی اسپیس یا همان تورفتگی ها ( Indentation ) در زبان برنامه نویسی پایتون اهمیت بسیار زیادی دارد. میزان تورفتگی کدها در خطوط تعیین میکند که کدام قسمت ها از کدهای شما هم گروه هستند.

مثال زیر را در نظر بگیرید :‌

x = 3
if x > 5:
    print('x is larger than 5')

دستور print در کد بالا در صورتی اجرا میشود که if مقدار true برگرداند یعنی print به if وابسته است چون تو رفتگی print از if یک تورفتگی بیشتر است.

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

قوانین تو رفتگی در pep8 زبان برنامه نویسی پایتون به شرح زیر است :‌

• از چهار space متوالی برای نشان دادن تو رفتگی ها استفاده کنید.
• ترجیحا از space ها به جای tab استفاده شود.

 

tab در مقابل space در کدنویسی :

همانطور که در بالا اشاره کردیم طبق قواعد pep-8 زبان پایتون بهتر است از space بجای tab با هدف تو رفتگی استفاده کنید.شما میتوانید در تنظیمات محیط کدنویسی خود تغییراتی را بدهید تا وقتی دکمه tab زده شد بصورت خودکار ۴ عدد space اعمال شود. اگر از پایتون نسخه ی ۲ استفاده میکنید و برای تو رفتگی ترکیبی از tab و space استفاده کردید Error خاصی نخواهید داشت.

البته شما میتوانید با اضافه کردن دستور -t در اجرای فایل پایتونی هشدارهای لازم مربوط به استفاده از tab و space را مشاهده کنید.

مثال زیر را ببینید :‌

$ python2 -t code.py
code.py: inconsistent use of tabs and spaces in indentation

همچنین شما میتوانید در پایتون نسخه ۲  از دستور -tt استفاده کنید تا بجای هشدار مفسر پایتون به شما Error نشان دهد تا دقیقا متوجه شوید خطای کار کجاست ‌: 

$ python2 -tt code.py
  File "code.py", line 3
    print(i, j)
             ^
TabError: inconsistent use of tabs and spaces in indentation

ولی پایتون ۳ اجازه ی ترکیب space و tab را به شما نمیدهد بنابراین اگر شما از نسخه ی ۳ پایتون استفاده میکنید بصورت پیشفرض به شما Error نشان داده خواهد شد : 

$ python3 code.py
  File "code.py", line 3
    print(i, j)
              ^
TabError: inconsistent use of tabs and spaces in indentation

شما در زبان پایتون مختار هستید که از space یا tab برای ایجاد تورفتگی کدها استفاده کنید اما اگر از نسخه ی پایتون ۳ استفاده میکنید باید با انتخاب خود سازگار باشید.

در غیر این صورت کد شما اجرا نمی شود و PEP 8 توصیه می کند که همیشه از ۴ عدد space متوالی برای ایجاد تورفتگی در کدهای پایتونی خود استفاده کنید.

 

ایجاد تورفتگی در زمان شکستن خطوط زبان پایتون

زمانی که شما از شکستن خطوط جهت حفظ ۷۹ کاراکتر در هر خط استفاده میکنید بهتر است برای خوانایی بالا از تورفتگی هم استفاده کنید.این کار به خواننده اجازه میدهد تا درک کند کدهای نوشته شده در یک خط واحد هستند یا یک خط بودند که حالا به چند خط شکسته شده اند.

در این حالت از برنامه نویسی با پایتون ،  دو استایل متفاوت تورفتگی وجود دارد.

 

اولین استایل در اینجا به شکلی ایجاد میشود که شما نقطه ی شروع خطوط شکسته شده را از جایی که شکسته شده است هم تراز کنید:

def function(arg_one, arg_two,
             arg_three, arg_four):
    return arg_one

بعضی اوقات شما به راحتی و تنها با ۴ عدد space میتوانید ابتدای خط شکسته شده را با نقطه ی آغاز جدا کننده در خط اصلی هم تراز کنید. اما گاهی ممکن است این فاصله گذاری باعث اشتباهاتی شود مثلا اگر if دارید که به خطوط پایینی شکسته شده است شرط های داخل if و همچنین مقدار داخل شرط در یک تراز قرار میگیرند که خوانایی کدها را سخت تر میکند. مثال زیر را ببینید :‌

x = 5
if (x > 3 and
    x < 10):
    print(x)

برای حل این موضوع pep-8 برای برنامه نویسی تمیز با پایتون دو راه حل ارائه داده است:

1. میتوانید بین شرط های درون if و همچنین محتویات داخل خود if یک کامنت بگذارید که از هم جدا کند . مثل کد زیر : 
   

   x = 5
   if (x > 3 and
       x < 10):
       # Both conditions satisfied
       print(x)

2. میتوانید برای شرط های داخل if یک تورفتگی اضافی ( ۴ عدد space ) در نظر بگیرید. مثل کد زیر :‌
   

   x = 5
   if (x > 3 and
           x < 10):
       print(x)

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

در زیر یک مثال داریم :‌

var = function(
    arg_one, arg_two,
    arg_three, arg_four)

نکته : طبق توصیه ی  pep-8 وقتی از استایل hanging indent استفاده میکنید نباید هیچ متغیری در خط اول باشد . مثال زیر این اشتباه را نشان میدهد :‌

# Not Recommended
var = function(arg_one, arg_two,
    arg_three, arg_four)

وقتی از شیوه ی hanging indent برای توابع استفاده میکنید  بهتر است برای محتویات درون تابع یک تورفتگی اضافی در نظر بگیرید تا کدنویسی پایتونی شما تمیزتر باشد. مثال زیر که یک تابع است خوانایی بدی دارد زیرا محتویات درون تابع به همان مقدار تورفتگی دارد که خطوط شکسته دارد:‌

# Not Recommended
def function(
    arg_one, arg_two,
    arg_three, arg_four):
    return arg_one

بجای کد بالا شما میتوانید از تورفتگی اضافی برای آرگومان های تابع استفاده کنید تا از محتوای درون تابع جدا شوند و خوانایی کدهای شما با زبان پایتون بالاتر برود :‌

def function(
        arg_one, arg_two,
        arg_three, arg_four):
    return arg_one

 

در کدنویسی تمیز پایتون کجا باید براکت ها را ببندیم ؟‌

شکستن خطوط در کدنویسی پایتون به شما اجازه میدهد محتویات درون پارانتز ها ، آکولادها و براکت ها را بشکنید و در خطوط جدیدی بنویسید اما مهم است که این کار را به شکل معقولی انجام دهیم در غیر این صورت برای خواننده ی کدهای ما مشکل خواهد بود طبق قواعد pep-8 پایتون دو گزینه برای این مورد معرفی کرده است که نشان میدهد کجا براکت ها را ببندیم :‌

1. براکت بسته را با اولین کاراکتر خط بالایی هم تراز کنیم . مثال : 
   

   list_of_numbers = [
       1, 2, 3,
       4, 5, 6,
       7, 8, 9
       ]

2. براکت بسته را هم تراز با اولین کاراکتر اولین خط یا خط اصلی بکنیم . مثال : 
   

   list_of_numbers = [
       1, 2, 3,
       4, 5, 6,
       7, 8, 9
   ]

از هر کدام از موارد بالا میتوانید به اختیار استفاده کنید در ضمن پرانتز براکت و اکولاد فرقی در این مسئله ندارد.

 

کامنت گذاری صحیح در Python

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

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

در اینجا چند نکته ی کلیدی هست که موقع کامنت گذاری در کدنویسی پایتون رعایت کنید :‌

• طول هر خط کامنت را حداکثر ۷۲ کاراکتر در نظر بگیرید.
• از جملات کامل استفاده کنید که حرف اول آن با حروف بزرگ شروع شود.
• اگر کدهای خود را بروزرسانی میکنید حتما قسمت کامنت مربوطه را هم بروزرسانی کنید.

 

کامنت  های بلاکی در پایتون 

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

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

اصول pep 8 پایتون قواعد زیر را برای کامنت گذاری بلاکی معرفی کرده است :‌

• تورفتگی کامنت بلاکی را دقیقا هم تراز با کدهای مربوط به خودش قرار  دهید.
• هر خط از کامنت بلاکی را با # شروع کنید و یک فاصله بعد از هشتگ قرار دهید.
• هر پاراگراف را با یک خط خالی که فقط با # شروع میشود از هم جدا کنید.

در زیر یک کامنت بلاکی آورده ایم که عملکرد یک حلقه ی for را نشان میدهد توجه کنید که خطوط شکسته شده تا اصول ۷۹ کاراکتر در هر خط رعایت شود :‌

for i in range(0, 10):
    # Loop over i ten times and print out the value of i, followed by a
    # new line character
    print(i, '\n')

بعضی مواقع که کدها پیچیده تر هستند و برای کامنت گذاری بیش از یک پاراگراف نیاز است به شکل زیر عمل میکنیم :‌

def quadratic(a, b, c, x):
    # Calculate the solution to a quadratic equation using the quadratic
    # formula.
    #
    # There are always two solutions to a quadratic equation, x_1 and x_2.
    x_1 = (- b+(b**2-4*a*c)**(1/2)) / (2*a)
    x_2 = (- b-(b**2-4*a*c)**(1/2)) / (2*a)
    return x_1, x_2

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

 

کامنت های خطی یا inline در پایتون

کامنت های خطی در پایتون فقط یک Statement از کدها را توضیح میدهند و در خوانایی کدها بسیار اهمیت دارند .  چیزی که PEP 8 پایتون درباره ی  کامنت تک خطی میگوید این است :‌

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

در زیر نمونه ای از کامنت خطی را مشاهده میکنید : 

x = 5  # This is an inline comment

بعضی جاها کامنت خطی ممکن است ضروری به نظر برسد ولی با نامگذاری صحیح میتوانید از کامنت گذاری خطی صرف نظر کنید مثال زیر را ببینید :‌

x = 'John Smith'  # Student Name

اینجا کامنت گذاری خطی برای روشن کردن اینکه x چیست خوب است ولی نامگذاری متغیر x به خودی خود مشکل زا است و اگر انرا اصلاح کنیم دیگر نیاز به کامنت نخواهد بود مثل زیر‌: 

student_name = 'John Smith'

در نهایت مثال های زیر چند نوع کامنت خطی بد تلقی میشوند چون از بدیهیات هستند و نیاز به کامنت نبوده :‌

empty_list = []  # Initialize empty list

x = 5
x = x * 5  # Multiply x by 5

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

 

مستندات رشته ای یا Documentation Strings در پایتون 

مستندات رشته ای ( Documentation strings ) یا docstrings نوعی متون هستند که داخل دو عدد """ قرار میگیرند و در ابتدای تابع ، کلاس ، متود یا ماژول نوشته میشوند.  شما میتوانید از آن برای توضیح یک بلاک از کدهای خود استفاده کنید. همچنین در pep-257 پایتون بصورت مفصل به مستندات رشته ای پرداخته شده است ولی ما اینجا هم توضیح میدهیم.

مهم ترین قوانین که برای docsyrings وجود دارد در زیر نوشته ایم :‌

• مستندات رشته ای را در بین دو عدد """ ( سه دابل کوتشن پشت سرهم ) باید قرار دهید. مثل :‌""" i am example for docstrings """
• آنها را برای همه ماژول ها، توابع، کلاس ها و متدهای عمومی استفاده کنید.
• هر وقت توضیحات شما چند خطی شد کاراکترهای """ مربوط به بستن docstring را در یک خط مجزا قرار دهید مثال : 
  

  def quadratic(a, b, c, x):
      """Solve quadratic equation via the quadratic formula.
  
      A quadratic equation has the following form:
      ax**2 + bx + c = 0
  
      There always two solutions to a quadratic equation: x_1 & x_2.
      """
      x_1 = (- b+(b**2-4*a*c)**(1/2)) / (2*a)
      x_2 = (- b-(b**2-4*a*c)**(1/2)) / (2*a)
  
      return x_1, x_2

• اگر docstring شما تک خطی است شروع پایان آنرا درون همان خط اعمال کنید مثال :‌
  

  def quadratic(a, b, c, x):
      """Use the quadratic formula"""
      x_1 = (- b+(b**2-4*a*c)**(1/2)) / (2*a)
      x_2 = (- b-(b**2-4*a*c)**(1/2)) / (2*a)
  
      return x_1, x_2

به همین سادگی و خوشمزگی !

 

فاصله بین عبارت های مختلف پایتون

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

 

فضای خالی در اطراف عملگرهای باینری 

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

• عملگرهای انتساب ( =, +=, -=  و ... )
• عملگرهای مقایسه ای ( ==, !=, >, <. >=, <= ) و ( is, is not, in, not in )
• عملگرهای بولین ( and, not, or )

نکته : زمانی که از = برای انتساب مقدار پیشفرض در توابع استفاده میکنید از فاصله استفاده نکنید. به مثال زیر دقت کنید :‌

# Recommended
def function(default_parameter=5):
    # ...


# Not recommended
def function(default_parameter = 5):
    # ...

وقتی در یک statement خاص چند متغیر وجود دارد که عملگر بین آنهاست استفاده از فاصله برای تمام آنها کمی گیج کننده خواهد بود. در این حالت بهتر است فاصله را فقط برای عملگرهایی اعمال کنید که اولویت کمتری دارد. به مثال زیر دقت کنید :

# Recommended
y = x**2 + 5
z = (x+y) * (x-y)

# Not Recommended
y = x ** 2 + 5
z = (x + y) * (x - y)

همچنین میتوانید این قانون رو برای شرط if اعمال کنید که در آن شرایط متعددی بررسی میشود. کدنویسی زیر پیشنهاد نمیشود : 

# Not recommended
if x > 5 and x % 2 == 0:
    print('x is larger than 5 and divisible by 2!')

 در عوض بهتر است فاصله بین and باشد که کمترین اولویت را نسبت به بقیه دارد در این صورت کد شما خواناتر خواهد بود :‌

# Recommended
if x>5 and x%2==0:
    print('x is larger than 5 and divisible by 2!')

همچنین اگر شرط بالا را به شکل زیر بنویسید غیرقابل قبول خواهد بود :‌

# Definitely do not do this!
if x >5 and x% 2== 0:
    print('x is larger than 5 and divisible by 2!')

زمانی که عمل slice انجام میدهید دو نقطه بعنوان یک اپراتور مثل اپراتورهای بالا حساب میشود. پس قوانین بالا را باید برای آن نیز اعمال کنید . به مثال های زیر دقت کنید :‌

list[3:4]

# Treat the colon as the operator with lowest priority
list[x+1 : x+2]

# In an extended slice, both colons must be
# surrounded by the same amount of whitespace
list[3:4:5]
list[x+1 : x+2 : x+3]

# The space is omitted if a slice parameter is omitted
list[x+1 : x+2 :]

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

 

ممنوعیت ها برای فاصله خالی در پایتون جهت خوانایی کدها

در بعضی حالت ها افزودن فاصله ی خالی نه تنها به خوانایی کدهای پایتون کمک نمیکند بلکه از نظر ظاهری درک آنرا سخت تر هم میکند. اصول pep-8 مثال های بسیار واضحی را برای درک حالت هایی که فاصله خالی در آن ممنوع است آورده که در زیر به آنها میپردازیم.

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

 

در ادامه لیستی از ممنوعیت ها آماده کرده ایم که در این حالت ها نباید از فاصله یا فضای خالی استفاده کنید :‌

1. بلافاصله درون پرانتز ، براکت یا آکولاد ها :‌
   

   # Recommended
   my_list = [1, 2, 3]
   
   # Not recommended
   my_list = [ 1, 2, 3, ]

2. قبل از کاما یا کولن یا سمی کولن : 
   

   x = 5
   y = 6
   
   # Recommended
   print(x, y)
   
   # Not recommended
   print(x , y)

3. قبل از پرانتز مربوط به توابع :‌
   

   def double(x):
       return x * 2
   
   # Recommended
   double(3)
   
   # Not recommended
   double (3)

4. قبل از براکت باز و بعد از نام مربوط به لیست :
   

   # Recommended
   list[3]
   
   # Not recommended
   list [3]

5. ما بین کاما پایانی و پرانتز بسته : 
   

   # Recommended
   tuple = (1,)
   
   # Not recommended
   tuple = (1, )

6. برای تراز کردن عملگرهای انتسابی‌:‌
   

   # Recommended
   var1 = 5
   var2 = 6
   some_long_var = 7
   
   # Not recommended
   var1          = 5
   var2          = 6
   some_long_var = 7

 

در آخر مطمئن شوید که trailing whitespace در هیچ کجای کدهای شما وجود ندارد ( بالاتر درباره اش توضیح دادیم ) .

 

توصیه هایی برای برنامه نویسی سالم در پایتون 

در هنگام برنامه نویسی با پایتون ( یا دیگر زبان های برنامه نویسی ) متوجه خواهید شد که برای انجام یک کار چندین راه وجود دارد. در این بخش برخی از پیشنهادات موجود در Pep-8 پایتون برای رفع ابهام آورده ایم.

 

توصیه شماره ۱ :

هرگز یک مقدار boolean را با استفاده از عملگر تساوی ( == ) با مقدار true و false مقایسه نکنید.همه میدانیم که موقع کدنویسی اغلب نیاز داریم یک مقدار را از نظر boolean بررسی کنیم که true هست یا false . در چنین حالتی به شکل زیر عمل کنیم‌:‌

# Not recommended
my_bool = 6 > 5
if my_bool == True:
    return '6 is bigger than 5'

کد بالا پیشنهاد نمیشود چون یک مقدار bool درون خود true یا false بودنش را دارد و نیاز نیست حتما با == چک شود کافیست یک شرط ساده بنویسید در صورت true بودن اجرا میشود :‌

# Recommended
if my_bool:
    return '6 is bigger than 5'

کد دوم ساده تر و زیبا هست و نیاز به نوشتن چیزهای اضافی هم نیست پس pep-8 آنرا توصیه میکند.

 

توصیه شماره ۲ :‌

زمانی که بخواهید خالی بودن محتوای یک لیست را بررسی کنید معمولا طول آن لیست را حساب میکنید و اگر تابع len که طول لیست را برمیگرداند عدد صفر برگرداند یعنی لیست خالی است. همه میدانیم که عدد صفر در حالت bool برابر false است. کد زیر میتواند پیشنهاد شود ولی از نظر pep-8 پیشنهاد نمیشود :‌

# Not recommended
my_list = []
if not len(my_list):
    print('List is empty!')

در هر حال میدانیم که در زبان برنامه نویسی پایتون زمانی که لیست ، رشته یا یک تاپل خالی باشد مقدار false برمیگرداند و ما میتوانیم از این برای سادگی کدهای خود استفاده کنیم. پس پیشنهاد میشود کد بالا به شکل زیر نوشته شود :‌

# Recommended
my_list = []
if not my_list:
    print('List is empty!')

نتیجه هر دو قطعه کد بالا یکسان است ولی طبق قواعد pep-8 پایینی بخاطر سادگی آن پیشنهاد میشود.

 

توصیه شماره ۳ :

از is not در شرط بجای note ... is استفاده کنید. اگر قصد دارید یک متغیر را از نظر دارا بودن محتوا چک کنید دو گزینه وجود دارد:

1. در حالت  اول شما داخل if با استفاده از is not متغیر را چک میکنید که این روش پیشنهاد میشود:
   

   # Recommended
   if x is not None:
       return 'x exists!'

2. درحالت دوم در داخل if چک میکنید که ابتدا x مقدارش None هست و سپس not همان را در نظر میگیرید که این روش پیشنهاد  نمیشود:
   

   # Not recommended
   if not x is None:
       return 'x exists!'

هر چند که دو قطعه کد بالا از نظر سینتکسی درست است ولی مورد اول کدنویسی تمیزتری میباشد و pep-8 نیز همان را پیشنهاد کرده است.

 

توصیه شماره ۴ :‌

اگر در شرط if منظور شما if x is not None هست بجای آن از if x: استفاده نکنید. یک اشتباه رایج این است که وقتی ما مقدار none یا خالی بودن را چک میکنیم و گاهی آنرا با false اشتباه میگیریم که none همیشه به معنی false نیست به مثال های زیر دقت کنید تا درک کنید:

# Not Recommended
if arg:
    # Do something with arg...

کد بالا مقدار متغیر arg را از نظر true بودن چک میکند و اگر مقدار آن true باشد به درون if میرود. ولی بعضی مواقع ما نیاز داریم None یا خالی بودن یک متغیر را بررسی کنیم که با کد بالا ممکن نیست مثال زیر را ببینید :‌

# Recommended
if arg is not None:
    # Do something with arg...

این خطاست که ما فکر کنیم اگر false باشد یعنی همان none ! اما فرض کنید متغیر ما یک لیست خالی به شکل زیر باشد : 

arg = []

همه میدانیم که این متغیر اکنون داخل if مقدارش false است چون یک لیست خالی است ولی این متغیر به معنی none بودن نیست پس کد اولی درست کار نمیکند چون متغیر ما none نیست ولی چون false برمیگرداند داخل شرط وارد نمیشود.

 

توصیه شماره ۵ : 

از توابع startswith و endswith بجای slice کردن استفاده کنید. اگر شما بخواهید بررسی کنید که یک رشته دارای پسوند یا پیشوند خاصی برای مثال عبارت cat است به نظر میرسد استفاده از slice بهترین روش است.

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

همچنین برای کسانی که با list های پایتون کمتر آشنا هستند این مورد گنگ خواهد بود:

# Not recommended
if word[:3] == 'cat':
    print('The word starts with "cat"')

و وقتی از تابع startwith استفاده میکنیم : 

# Recommended
if word.startswith('cat'):
    print('The word starts with "cat"')

همینطور برای بررسی پسوند بودن یک کلمه ی خاص از این روش استفاده میشود در کد زیر که  بررسی میشود که یک رشته به jpg ختم شود ولی این روش پیشنهاد نمیشود :‌

# Not recommended
if file_name[-3:] == 'jpg':
    print('The file is a JPEG')

هر چند که کد بالا درست کار میکند ولی خوانایی کمتری دارد و از تابع endswith میتوانید برای خوانایی بالاتر استفاده کنید که پیشنهادی pep 8 پایتون است ‌:

# Recommended
if file_name.endswith('jpg'):
    print('The file is a JPEG')

همانند تمامی قسمت های بالا در این مقاله این بخش نیز به این منظور نوشته شده که با کمک آن بتوانید کدهای تمیزتر و مرتب تری بنویسید که خوانایی بالایی داشته باشند . در حالت کلی در زبان برنامه نویسی پایتون برای نوشتن کد های مربوط به یک کار میتواند به شیوه های مختلفی نوشته شود ولی بهتر است کدنویسی اصولی و تمیز داشته باشید.

 

چه زمانی از PEP 8 پایتون استفاده نکنیم ؟‌

پاسخ به این سوال بصورت مختصر این است : هیچ موقع !‌ چون استفاده ی درست و اصولی از قواعد pep 8 به کدهای شما نظم میدهد و باعث میشود کدنویسی تمیزی با زبان برنامه نویسی پایتون انجام دهید. استفاده از pep 8 هم برای خودتان هم برای همکاران و کارفرمایان مفید است.

به هر حال برخی از قواعد pep 8 که در زیر آورده ایم ناخوشایند هستند :‌

1. اگر پیروی از pep 8 باعث از بین رفتن سازگاری موجود در نرم افزار جاری میشود.
2. اگر پیرامون پروژه ای که کار میکنید با pep 8 سازگار نیست.
3. اگر کد شما با نسخه های قدیمی پایتون باید سازگار بماند.

 

نکات و ترفند هایی برای اطمینان از اینکه کد شما از pep 8 پیروی میکند

برای اطمینان از اینکه کدهای شما مطابق با PEP 8 پایتون است، چیزهای زیادی را باید به خاطر بسپارید. به خاطر سپردن همه این قواعد و اصول در هنگام توسعه پروژه های پایتونی می تواند کار سختی باشد.

همچنین آپدیت کردن پروژه های قدیمی برای سازگاری با pep 8 نیز زمان بر است. خوشبختانه ابزارهایی ساخته شده که به شما کمک کند تا با سرعت بالا pep 8 را روی پروژه های پایتونی خود اعمال کنید.

دو نوع ابزارها وجود دارد که اینجا میتوانید از انها استفاده کنید : linter ها و autoformatter ها

 

Linter ها در پایتون

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

لینترها به ویژه هنگامی مفید هستند که به عنوان افزونه به محیط کدنویسی  شما نصب میشوند، زیرا هنگام توسعه ی پروژه ، خطاها و مشکلات استایل کدها را نشان می دهند.

در این بخش میبینید که چطور linter ها کار میکنند.

بهترین ابزارهای linter برای کدنویسی پایتون به شرح زیر هستند :‌

• pycodestyle : ابزاری برای بررسی مطابقت کدهای پایتونی شما با قواعد pep 8 است. شما میتوانید pycodestyle را از طریق pip نصب کنید :‌
  

  pip install pycodestyle

  همچنین میتوانید pycodestyle را از طریق ترمینال یا کامند لاین به شکل زیر اجرا کنید :‌

  pycodestyle code.py
  code.py:1:17: E231 missing whitespace after ','
  code.py:2:21: E231 missing whitespace after ','
  code.py:6:19: E711 comparison to None should be 'if cond is None:'

   

• flake8 : ابزاری است به همراه یک دیباگر ، pyflakes را با pycodestyle ترکیب میکند.برای نصب با pip دستور زیر را اجرا کنید : 
  

   pip install flake8

  شما میتوانید flake8 را از طریق ترمینال به شکل زیر اجرا کنید :‌

•  

  $ flake8 code.py
  code.py:1:17: E231 missing whitespace after ','
  code.py:2:21: E231 missing whitespace after ','
  code.py:3:17: E999 SyntaxError: invalid syntax
  code.py:6:19: E711 comparison to None should be 'if cond is None:'

برای ابزارهای معرفی شده در بالا افزونه هایی وجود دارد که داخل محیط های برنامه نویسی قابل نصب است محیط هایی مثل :
 Sublime Text, Visual Studio Code, and VIM

 

Autoformatter در زبان برنامه نویسی پایتون 

در پایتون Autoformatter ها نرم افزارهایی هستند که کدهای شما را pep 8 مطابقت میدهند. نام یکی از این نرم افزارها black است که با پیروی از قواعد pep 8 کدهای شما را بصورت خودکار فرمت میکند.

یکی از تفاوت های این نرم افزار این است که تعداد کاراکترهای هر خط را ۸۸ عدد در نظر میگیرد که البته با یک دستور میتوانید اعلام کنید که از این به بعد خطوط من را ۷۹ کاراکتر حساب کن.

شما میتوانید black را از طریق دستور pip زیر نصب کنید. برای اجرای black به پایتون نسخه ی ۳.۶ به بالا نیاز است : 

$ pip install black

این ابزار هم قابلیت این را دارد که اطریق ترمینال یا کامند لاین اجرا شود ما یک نمونه کد پایتون مینویسیم و در فایل code.py ذخیره میکنیم :‌

for i in range(0,3):
    for j in range(0,3):
        if (i==2):
            print(i,j)

سپس از طریق ترمینال دستور زیر را اجرا میکنیم : 

$ black code.py
reformatted code.py
All done! ✨                 

برای تعیین طول هر خط که باید ۷۹ کاراکتر باشد از پرچم --line-length استفاده کنید : 

$ black --line-length=79 code.py
reformatted code.py
All done! ✨                 

همچنین دو نوع فرمت کننده برای پایتون وجود دارد به نام های autopep8 و yapf که مشابه black عمل میکنند.

 

نتیجه گیری : 

اکنون در پایان این مقاله ی آموزشی بلند هستیم و الان میدانید که pep 8 چیست . شاید اصول pep 8 ساده به نظر برسند ولی رعایت کردن آنها باعث میشود کدهای با کیفیت بالا و تمیز بنویسید مخصوصا زمانی که قرار است پروژه ی پایتونی خود را به افراد دیگری بدهید.

در این مقاله ی آموزشی بصورت کلی موارد زیر را یاد گرفتیم : 

• اصول pep 8 چیست و اصلا چرا بوجود آمده اند ؟ 
• چرا باید هدف برنامه نویسان پایتون نوشتن کدی با رعایت اصول pep 8 باشد ؟‌
• چگونه کدی بنویسیم که مطابق با اصول pep-8 باشد ؟ 

علاوه بر همه اینها، نحوه استفاده از Linter ها و Autoformatter ها را برای بررسی کدهای پایتون در برابر دستورالعمل های PEP 8 نیز آموزش دادیم.