Pocoo Styleguide¶

Общая планировка¶

Отступы:

4 реальных пробела. Никаких вкладок, никаких исключений.

Максимальная длина линии:

79 символов с мягким ограничением до 84, если это абсолютно необходимо. Старайтесь избегать слишком вложенного кода, грамотно размещая утверждения break, continue и return.

Продолжение длинных высказываний:

Чтобы продолжить высказывание, можно использовать обратные косые черты, в этом случае следующую строку следует выровнять по последней точке или знаку равенства, или сделать отступ в четыре пробела:

this_is_a_very_long(function_call, 'with many parameters') \
    .that_returns_an_object_with_an_attribute

MyModel.query.filter(MyModel.scalar > 120) \
             .order_by(MyModel.name.desc()) \
             .limit(10)

Если вы заключаете высказывание в круглые скобки или фигурные скобки, выравнивайте его по скобкам:

this_is_a_very_long(function_call, 'with many parameters',
                    23, 42, 'and even more')

Для списков или кортежей с большим количеством элементов делайте паузу сразу после открывающей скобки:

items = [
    'this is the first', 'set of items', 'with more items',
    'to come in this line', 'like this'
]

Пустые линии:

Функции и классы верхнего уровня отделяются двумя строками, все остальное - одной. Не используйте слишком много пустых строк для разделения логических сегментов в коде. Пример:

def hello(name):
    print 'Hello %s!' % name


def goodbye(name):
    print 'See you %s.' % name


class MyClass(object):
    """This is a simple docstring"""

    def __init__(self, name):
        self.name = name

    def get_annoying_name(self):
        return self.name.upper() + '!!!!111'

Выражения и утверждения¶

Общие правила пробельных символов:

• Отсутствие пробелов для унарных операторов, которые не являются словами (например: -, ~ и т.д.), а также на внутренней стороне круглых скобок.

• Между двоичными операторами ставится пробел.

Хорошо:

exp = -1.05
value = (item_value / item_count) * offset / exp
value = my_list[index]
value = my_dict['key']

Плохо:

exp = - 1.05
value = ( item_value / item_count ) * offset / exp
value = (item_value/item_count)*offset/exp
value=( item_value/item_count ) * offset/exp
value = my_list[ index ]
value = my_dict ['key']

Высказывания Йоды - это «нет»:

Никогда не сравнивайте постоянное с переменным, всегда переменное с постоянным:

Хорошо:

if method == 'md5':
    pass

Плохо:

if 'md5' == method:
    pass

Сравнения:

• против произвольных типов: == и !=.

• против синглетонов с is и is not (например: foo is not None)

• никогда не сравнивайте что-то с True или False (например, никогда не делайте foo == False, вместо этого делайте not foo)

Отрицательные проверки сдерживания:

использовать foo not in bar вместо not foo in bar

Проверки экземпляров:

isinstance(a, C) вместо type(A) is C, но старайтесь избегать проверок экземпляров в целом. Проверьте наличие функций.

Соглашения об именовании¶

• Имена классов: CamelCase, при этом аббревиатуры должны быть в верхнем регистре (HTTPWriter, а не HttpWriter)

• Имена переменных: lowercase_with_underscores

• Имена методов и функций: lowercase_with_underscores

• Константы: UPPERCASE_WITH_UNDERSCORES

• предварительно скомпилированные регулярные выражения: name_re

Защищенные члены имеют префикс с одинарным подчеркиванием. Двойное подчеркивание зарезервировано для классов-миксинов.

К классам с ключевыми словами добавляются подчеркивания в конце. Столкновения со встроенными модулями допускаются и не должны устраняться добавлением подчеркивания к имени переменной. Если функция должна получить доступ к затененному встроенному модулю, перепривяжите встроенный модуль к другому имени.

Аргументы функций и методов:

• методы класса: cls в качестве первого параметра

• методы экземпляра: self в качестве первого параметра

• ламбды для свойств могут иметь первый параметр, замененный на x, как в display_name = property(lambda x: x.real_name or x.username)

Docstrings¶

Docstring conventions:

Все документные строки форматируются с помощью reStructuredText в понимании Sphinx. В зависимости от количества строк в doc-строке, они располагаются по-разному. Если это одна строка, то закрывающая тройная кавычка находится на той же строке, что и открывающая, в противном случае текст находится на той же строке, что и открывающая кавычка, а тройная кавычка, закрывающая строку, на своей строке:

def foo():
    """This is a simple docstring"""


def bar():
    """This is a longer docstring with so much information in there
    that it spans three lines.  In this case the closing triple quote
    is on its own line.
    """

Заголовок модуля:

Заголовок модуля состоит из объявления кодировки utf-8 (если используются не ASCII буквы, но это рекомендуется всегда) и стандартной docstring:

# -*- coding: utf-8 -*-
"""
    package.module
    ~~~~~~~~~~~~~~

    A brief description goes here.

    :copyright: (c) YEAR by AUTHOR.
    :license: LICENSE_NAME, see LICENSE_FILE for more details.
"""

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

Комментарии¶

Правила для комментариев аналогичны правилам для docstrings. Оба они форматируются с помощью reStructuredText. Если комментарий используется для документирования атрибута, поставьте двоеточие после открывающего знака фунта (#):

class User(object):
    #: the name of the user as unicode string
    name = Column(String)
    #: the sha1 hash of the password + inline salt
    pw_hash = Column(String)