Skip to content

Latest commit

 

History

History
188 lines (136 loc) · 8.01 KB

codestyle.md

File metadata and controls

188 lines (136 loc) · 8.01 KB
Raw

Codestyle памятки для написания более читабельного и лаконичного кода ✏️

Существует множество принципов, методов и лучших практик для написания чистого кода на Python. Ниже приведены несколько советов, которые помогут Вам начать работу и упростить процесс написания

Переменные

  • Имена переменных должны быть snake_case и в нижнем регистре first_name

  • Используйте информативные описательные имена, которые легко читаются.

    # Не рекомендуется
au = 105

# Рекомендуется
active_users = 105

  • Имена констант должны быть snake_case и в верхнем регистре LAST_NUMBER

  • Не используйте магические числа.

    # Не рекомендуется
def roll_dice():
    return random.randint(0, 4)  # what is 4 supposed to represent?

# Рекомендуется
DICE_SIDES = 4

def roll_dice():
    return random.randint(0, DICE_SIDES)

Функции

  • Имена функций должны быть snake_case и в нижнем регистре (quick_sort());

  • Вы должны подробно описывать, но только релевантную информацию. Например, хорошие имена функций описывают то, что они делают хорошо, не включая подробности

DICE_SIDES = 4

# Не рекомендуется
def roll_dice_using_randint():
    return random.randint(0, DICE_SIDES)

# Рекомендуется
def roll_dice():
    return random.randint(0, DICE_SIDES)

Использование пустого пространства

Максимальная длина строки. Постарайтесь ограничить свои строки примерно 79 символами, что является рекомендацией, приведенной в руководстве по стилю PEP 8

Аннотация типов

Чтобы держать типизацию под контролем — применяют аннотации типов данных Type Hints. Это явное указание типа ожидаемых данных при объявлении переменных, классов и функций.

Чтобы указать тип переменной в Python, просто добавьте двоеточие с пробелом, за которым следует тип (str, int, List[] и т. д.), сразу после имени переменной.

from typing import List

name: str = 'Tommy'
age: int = 24
height_in_meters: float = 1.7
colleagues: List[str] = ['Alicia', 'John']

В функциях указывают Type Hints для аргументов и возвращаемого значения , мы добавляем стрелку –>, за которой следует его тип.:

from typing import Dict, List


def convert_celcius_to_fahrenheit(celcius_temp: float) –> float:
    return (celcius_temp * 9/5) + 32

def send_email(subject: str, body: str, recipients: List[str], cache: Dict[str,str])–> bool:
    pass

Docstring: документирование кода

Рекомендации к оформлению комментариев:

  • начинайте комментарий со знака #;
  • первое слово пишите с заглавной буквы;
  • следите за длиной строки — она должна быть не больше 72 символов;
  • заканчивайте комментарий точкой.

Используйте комментарии, когда нужно:

  • указать на участок кода, на который стоит обратить внимание;
  • пояснить сложные алгоритмы или логику;
  • указать на код, который нужно доработать;
  • указать на код, который хочется позже разобрать.

Основные правила оформления докстрингов

  • После открывающих тройных кавычек """ не должно быть пробела. Докстринг начинается с заглавной буквы и заканчивается точкой:

     """Возвращает число 1."""

  • Если докстринг не умещается в одну строку — можно разбить его на несколько строк. Отступы на новой строке должны выровнять текст по кавычкам:

    def tricky_func():
      """Можно перенести
      так.
      """

  def muddy_func():
      """
      А можно -
      так.
      """

  • Если документируется класс — после строки документации оставляется пустая строка. В остальных случаях код должен начинаться сразу после докстринга.

Также о правилах оформления докстрингов можно ознакомиться подробнее в стандарте PEP257.

Django codestyle

F строка

  • f-строки должны использовать только простой доступ к переменным и свойствам с предварительным назначением локальной переменной для более сложных случаев:
# Разрешено
f'hello {user}'
f'hello {user.name}'
f'hello {self.user.name}'

# Не разрешено
f'hello {get_user()}'
f'you are {user.age * 365.25} days old'

Импорты

  • В каждой строке расположите элементы импорта в алфавитном порядке с элементами в верхнем регистре, перед элементами в нижнем регистре.

  • Разорвите длинные строки скобками и сделайте отступ на 4 пробела. Включите запятую после последнего импорта и поместите закрывающую круглую скобку в отдельную строку.

  • Используйте одну пустую строку между последним импортом и любым кодом уровня модуля и используйте две пустые строки над первой функцией или классом.

  • Например (комментарии предназначены только для пояснительных целей):

django / contrib / admin / example.py# future
from __future__ import unicode_literals

# standard library
import json
from itertools import chain

# third-party
import bcrypt

# Django
from django.http import Http404
from django.http.response import (
    Http404, HttpResponse, HttpResponseNotAllowed, StreamingHttpResponse,
    cookie,
)

# local Django
from .models import LogEntry

# try/except
try:
    import yaml
except ImportError:
    yaml = None

CONSTANT = 'foo'


class Example:
    # ...
  • По возможности используйте удобный импорт. Например, сделайте так:
from django.views import View

вместо:

from django.views.generic.base import View