آموزش PEP پایتون - آخرین نکات

May 2020

ویدیویی وجود ندارد

در این مقاله آخرین نکاتی که مربوط به PEP8 پایتون میشود را خواهید دید.

 

Source File Encoding

کدهایی که با پایتون3 نوشته میشوند همیشه باید از UTF-8 استفاده کنند، برای پایتون2 از ASCII استفاده کنید. در کدهای پایتون3 دیگر از encoding declaration استفاده نکنید. یعنی خط زیر را در کدهایتان قرار ندهید:

#!/usr/bin/env python
# -*- coding: UTF-8 -*-

 

Module Level Dunder Names

تمام اسامی dunder(آنهایی که با دو underscore شروع و تمام میشوند مثل __all__, __version__, __author__) باید بعد از docstringهای ماژول و قبل از تمام importها قرار گیرند بجز future. چون پایتون پیشنهاد میدهد که future-imports باید قبل از هر کدی قرار گیرد:

"""This is the example module.
This module does stuff.
"""

from  __future__  import  barry_as_FLUFL

__all__  =  ['a', 'b', 'c']
__version__  = '0.1'
__author__  = 'Cardinal Biggles'

import  os
import  sys

 

String Quotes

سعی کنید از quoteها به شکل مخالف استفاده کنید یعنی داخل Double quote از Single quote و داخل Single quote از Double quote استفاده کنید تا نیازی به استفاده از backslash نداشته باشید که باعث خوانایی کد خواهد شد. همچنین در زمان استفاده از سه quote برای docstringها از Double quote  استفاده کنید.

 

When To Use Commas

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

درست:

FILES  =  ('setup.cfg',)

بدون مشکل اما گیج کننده:

FILES  =  'setup.cfg',

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

درست:

FILES   =   [
     'setup.cfg',
     'tox.ini',
     ]
initialize(FILES,
            error=True,
          )

نادرست:

FILES  =  ['setup.cfg',  'tox.ini',]
initialize(FILES,  error=True,)

 

Comments

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

 

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

x = x + 1  # incremnting x

 

DocStrings

برای تمام ماژول‌ها، کلاس‌ها و متدهایتان که عمومی هستند docsting بنویسید. برای کدهایی که عمومی نیستند میتوانید از docstring استفاده نکنید اما حتما از یک کامنت استفاده کنید و مشخص کنید که کدتان چطور کار میکند. این کامنت باید بعد از خط def نوشته شود. دقت کنید زمانی که از docstringهای چند خطی استفاده میکنید """ پایانی باید در یک خط جدید باشد. اگر docstring تک خطی است """ را در همان خط بنویسید.

"""Return a foobang

Optional plotz says to frobnicate the bi
"""

 

Names To Avoid

هیچ وقت از کاراکترهای l (ال کوچک انگلیسی)، O (او بزرگ انگلیسی) و I (آی بزرگ انگیسی) به صورت تکی استفاده نکنید زیرا در برخی فونت‌ها این کاراکترها از عدد 1  و صفر انگلیسی قابل تشخیص نیستند.

 

Package, Module, Class, etc. Names

نام تمام ماژول‌ها باید کوتاه و به صورت حروف کوچک باشد و در شرایطی که به خوانایی کمک کند میتوانید از underscore استفاده کنید.

نام پکیج‌ها هم باید کوتاه و به صورت حروف کوچک باشد اما استفاده از underscore پیشنهاد نمیشود.

نام کلاس‌ها همیشه باید به شکل CamelCase باشد یعنی حرف اول هر کلمه به شکل بزرگ و بقیه حروف کوچک.

برای ایجاد کردن Exceptionها، از آنجایی که Exceptionها خود کلاس هستند، نام آنها از نام کلاس‌ها پیروی میکند و در نهایت باید کلمه Error به آخر نام اضافه شود.

نام فانکشن‌ها باید به شکل حروف کوچک و برای خوانایی بیشتر کلمات را به underscore جدا کنید.

برای آرگومان‌های متدها، اولین آرگومان را در instance methods حتما self بنامید و نام اولین آرگومان برای class methods حتما cls باشد. اگر نامی که برای آرگومان انتخاب میکنید با کلمات کلیدی مغایرت دارد از یک underscore تمام شونده استفاده کنید. هرگز کلمات را به صورت شکسته و ناقص ننویسید. _class بهتر از clss است.

برای ایجاد کردن constantها تمام حروف کلمات بزرگ و از underscore برای جدا کردن کلمات استفاده کنید: TOTAL_NUMBER

 

 

Programming Recommendations

تمام کدهایی که مینویسید نباید با مفسرهای دیگر پایتون مغایرت داشته باشند مثل Pypy, Jython, IronPython, Cython و غیره.

به عنوان مثال به روش cpython برای چسباندن دو رشته به یکدیگر اعتماد نکنید مثلا a += b یا a = a+b. این کد حتی در خود cpython هم به درستی کار نمیکند چه برسد به مفسرهای دیگر. بهتر است از متد joint استفاده شود.

مقایسه با None حتما باید با is یا is not انجام شود و نه از علامت = تا در همه مفسرها به درستی کار کند.

از is not به جای not ..... is استفاده کنید. هر دو یک نتیجه دارند اما روش اول خواناتر است.

درست:

if foo is not None:

نادرست:

if not foo is None:

 

زمانی که قرار است متدهای مقایسه‌ای را به برنامه اضافه کنید تمام شش متد را قرار دهید. ( __eq__ , __ne__ , __lt__ , __le__ ,
__gt__ , __ge__ ).

 

زمانی که میخواهید با استفاده از فانکشن یک متغیر را مقدار دهی کنید از def بجای lambda استفاده کنید

درست:

def f(x): return 2*x

نادرست:

f = lambda x: 2*x

 

برای ساختن exceptionها خودتان همیشه کلاس‌هایتان از Exception بجای BaseException ارثبری کنند. کلاس BaseException برای زمانی رزرو شده‌اند که اتفاق افتادن آنها کار اشتباهی است.

 

زمانی که قرار است از بلاک‌های try/except استفاده کنید سعی کنید بلاک try بسیار کوچک باشد و کمترین کد ممکن را در بلاک try قرار دهید.

درست:

try:
     value = collection[key]
except KeyError:
      return key_not_found(key)
else:
     return handle_value(value

نادرست:

try:
     # Too broad!
     return · handle_value(collection
except KeyError:
     # Will also catch KeyErro
     return key_not_found(key)

 

در رابطه با return کردن ثابت قدم باشید. یا تمام بلاک‌ها در فانکشن باید یک عبارتی را برگشت دهند یا هیچکدام نباید مقداری برگشت دهند. اگر بعضی از بلاک‌ها مقداری برای return کردن ندارند باید به صورت صریح return None کنند.

درست:

def foo(x):
if x >= 0:
         return math.sqrt(x)
     else:
         return · None
def bar(x):
     if x < 0:
         return None
     return math.sqrt(x)

نادرست:

def foo(x):
     if x >= 0:
         return math.sqrt(x)
def bar(x):
     if x < 0:
         return
     return math.sqrt(x)

 

ارسال نظر

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