.

راهنمای کامل PEP 8 در پایتون: بنویسیم که دیگران (و خودمان!) بفهمند

 

در دنیای برنامه‌نویسی پایتون، کدی که می‌نویسید تنها برای اجرا شدن نیست، بلکه باید خوانا، قابل فهم و قابل نگهداری باشد. اینجاست که PEP 8 وارد میدان می‌شود. PEP 8 که مخفف Python Enhancement Proposal 8 است، یک راهنمای سبک کدنویسی (Style Guide) برای زبان پایتون است که مجموعه‌ای از قوانین و بهترین شیوه‌ها را برای نوشتن کدهای تمیز و خوانا ارائه می‌دهد. پیروی از این استانداردها باعث می‌شود کدهای شما حرفه‌ای‌تر به نظر برسند و همکاری در پروژه‌های تیمی بسیار آسان‌تر شود.

 

این مقاله یک راهنمای جامع و آموزشی برای درک و به کارگیری اصول PEP 8 در پروژه‌های پایتون شماست.

 

چرا PEP 8 اینقدر مهم است؟ 

 

شاید از خود بپرسید چرا باید به سبک کدنویسی اهمیت دهیم؟ گیدو ون روسوم، خالق پایتون، جمله‌ی معروفی دارد: «کد بیشتر از آنکه نوشته شود، خوانده می‌شود.» این جمله به زیبایی اهمیت خوانایی کد را نشان می‌دهد. دلایل اصلی اهمیت PEP 8 عبارتند از:

 

  • خوانایی و درک بهتر کد: کدی که بر اساس یک استاندارد واحد نوشته شده باشد، برای همه (از جمله خود شما در آینده) قابل فهم‌تر است.
  • نگهداری و توسعه آسان‌تر: پیدا کردن خطاها (Debugging) و افزودن ویژگی‌های جدید به کدی که ساختار منظمی دارد، بسیار ساده‌تر است.
  • همکاری تیمی مؤثرتر: وقتی همه اعضای تیم از یک سبک کدنویسی پیروی می‌کنند، تداخل‌ها به حداقل می‌رسد و همه می‌توانند به راحتی کد یکدیگر را درک کرده و روی آن کار کنند.
  • نشانه‌ی حرفه‌ای بودن: رعایت استانداردهای کدنویسی نشان می‌دهد که شما یک توسعه‌دهنده‌ی دقیق و حرفه‌ای هستید.

مهم‌ترین اصول PEP 8 که باید بدانید

 

در ادامه به بررسی کلیدی‌ترین و پرکاربردترین قوانین PEP 8 می‌پردازیم.

 

۱. تورفتگی (Indentation)

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

  • قانون: از ۴ فاصله (Space) برای هر سطح از تورفتگی استفاده کنید.

اشتباه:

if x > 5:
 print("x is greater than 5")

صحیح:

if x > 5:
    print("x is greater than 5")

 

نکته: استفاده از Tab به جای فاصله توصیه نمی‌شود، زیرا ممکن است در ویرایشگرهای مختلف به صورت‌های متفاوتی نمایش داده شود و باعث ایجاد خطا گردد. اکثر ویرایشگرهای کد مدرن را می‌توان طوری تنظیم کرد که با فشردن کلید Tab، ۴ فاصله درج شود.

 

۲. طول خطوط (Line Length)

طولانی بودن خطوط کد، خوانایی آن را به شدت کاهش می‌دهد، به خصوص در نمایشگرهای کوچک.

 

  • قانون: طول هر خط کد نباید بیشتر از ۷۹ کاراکتر باشد. برای مستندات (Docstrings) و کامنت‌ها، این محدودیت ۷۲ کاراکتر است.

 

برای شکستن خطوط طولانی می‌توانید از پرانتز ()، کروشه [] یا آکولاد {} استفاده کنید. پایتون به طور خودکار خطوط داخل این کاراکترها را به هم متصل می‌کند.

مثال برای شکستن یک عبارت طولانی:

 

def my_function(arg_one, arg_two,
                arg_three, arg_four):
    # کد تابع
    pass

total = (first_variable
         + second_variable
         - third_variable)

۳. خطوط خالی (Blank Lines)

 

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

 

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

مثال:

 

class MyClass:
    def first_method(self):
        # کد متد اول
        pass

    def second_method(self):
        # کد متد دوم
        pass


def first_function():
    # کد تابع اول
    pass


def second_function():
    # کد تابع دوم
    pass

۴. وارد کردن ماژول‌ها (Imports)

 

نحوه وارد کردن کتابخانه‌ها و ماژول‌ها نیز از قوانین خاصی پیروی می‌کند.

 

  • قانون:
    • همیشه import ها را در ابتدای فایل و بعد از کامنت‌ها و Docstring های ماژول قرار دهید.
    • هر import باید در یک خط جداگانه باشد.

اشتباه:

import sys, os

صحیح:

import os
import sys
  • ترتیب import ها:
    1. کتابخانه‌های استاندارد پایتون (مانند os, sys)
    2. کتابخانه‌های سوم شخص (Third-party) (مانند numpy, pandas)
    3. ماژول‌های محلی پروژه خودتان

مثال:

# کتابخانه‌های استاندارد
import os
import sys

# کتابخانه‌های سوم شخص
import numpy as np

# ماژول‌های محلی
from my_project import my_module

 

۵. فاصله‌گذاری در عبارات (Whitespace in Expressions)

استفاده صحیح از فاصله‌ها، خوانایی عبارات ریاضی و منطقی را بسیار بهبود می‌بخشد.

 

  • قانون:
    • دور عملگرهای محاسباتی (+, -, *, /, =), مقایسه‌ای (==, !=, >, <) و منطقی (and, or, not) یک فاصله قرار دهید.
    • بعد از کاما (,) و دونقطه (:) یک فاصله بگذارید.
    • فاصله‌ای بین نام تابع و پرانتز آرگومان‌های آن قرار ندهید.

اشتباه:

x= y*2+1
if x>5:print(x)
my_list=[1,2,3]

صحیح:

x = y * 2 + 1
if x > 5:
    print(x)
my_list = [1, 2, 3]
my_function(x, y)

۶. قراردادهای نام‌گذاری (Naming Conventions)

 

انتخاب نام‌های مناسب و استاندارد یکی از مهم‌ترین بخش‌های PEP 8 است.

 

متغیرها، توابع و متدها: از حروف کوچک و برای جدا کردن کلمات از آندرلاین (_) استفاده کنید (سبک snake_case).

مثال: user_name, calculate_average_price()

کلاس‌ها: از سبک CapWords یا PascalCase استفاده کنید (حرف اول هر کلمه بزرگ باشد و کلمات به هم چسبیده باشند).

مثال: DatabaseConnection, UserProfile

ثابت‌ها (Constants): از حروف بزرگ و برای جدا کردن کلمات از آندرلاین استفاده کنید.

مثال: MAX_OVERFLOW, PI

ماژول‌ها و پکیج‌ها: نام‌های کوتاه، با حروف کوچک و بدون آندرلاین. اگر نیاز به جداسازی بود، از آندرلاین استفاده کنید.

مثال: requests, my_package

 

۷. کامنت‌ها (Comments)

کامنت‌ها باید مفید، مختصر و به‌روز باشند.

 

  • کامنت‌های بلوکی (Block Comments): برای توضیح یک بخش از کد به کار می‌روند و باید تورفتگی آن‌ها با کدی که توضیح می‌دهند یکسان باشد. هر خط با # و یک فاصله شروع می‌شود.

  • # این حلقه برای محاسبه مجموع اعداد زوج در لیست است
total = 0
for number in numbers:
    if number % 2 == 0:
        total += number

 

کامنت‌های خطی (Inline Comments): در همان خط دستور قرار می‌گیرند و باید حداقل دو فاصله با کد داشته باشند. از آن‌ها کم و برای توضیحات ضروری استفاده کنید.

x = x + 1  # افزایش شمارنده

رشته‌های مستندات (Docstrings): برای مستندسازی توابع، کلاس‌ها و ماژول‌ها استفاده می‌شوند و باید داخل سه علامت نقل قول """ قرار گیرند. Docstring باید اولین عبارت در بدنه تابع یا کلاس باشد و توضیح دهد که آن قطعه کد چه کاری انجام می‌دهد.

def calculate_sum(a, b):
    """
    این تابع دو عدد را به عنوان ورودی گرفته و مجموع آن‌ها را برمی‌گرداند.
    """
    return a + b

ابزارهای کمکی برای رعایت PEP 8

نگران نباشید! لازم نیست تمام این قوانین را حفظ کنید. ابزارهای زیادی وجود دارند که به شما در بررسی و اصلاح خودکار کدتان کمک می‌کنند:

Linters: ابزارهایی مانند flake8 و pylint کد شما را به صورت زنده بررسی کرده و هرگونه مغایرت با PEP 8 را به شما اطلاع می‌دهند.

Formatters: ابزارهایی مانند black, autopep8 و yapf می‌توانند به طور خودکار کدهای شما را بر اساس قوانین PEP 8 قالب‌بندی کنند. black به دلیل سخت‌گیری و ایجاد یک سبک کاملاً یکسان در پروژه‌ها، محبوبیت زیادی پیدا کرده است.

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

نکته مهم

این یک باکس برای نمایش نکات کلیدی و مهم است. می‌توانید از این ساختار در ویرایشگر متن خود برای برجسته کردن بخش‌های خاصی از محتوا استفاده کنید.