Выделена версия 0.0.1

README.rst

@@ -0,0 +1,309 @@
+Yet Another Python Style Guide
+==============================
+
+:Версия: 0.0.1
+:Авторы: - Алексей Партилов ([email protected])
+
+Общие положения
+---------------
+
+Руководство по стилю оформления оформления кода применяется ко всем проектам
+написанным на языке Python вне зависимости от версии языка и вне зависимости от
+типа и версии используемого фреймворка.
+
+В большинстве случаев руководство следует стандарту PEP8 и дополняется
+правилами из статического анализатора кода Flake8. В случае если при написании
+кода у разработчика возникает ситуация которая не разрешается данным
+руководством, то разработчик должен руководствоваться следующими документами:
+
+1. Коды ошибок и предупреждений Flake8 https://flake8.readthedocs.org/en/latest/warnings.html
+2. Стандарт PEP 257 https://www.python.org/dev/peps/pep-0257/
+3. Стандарт PEP 8 https://www.python.org/dev/peps/pep-0008/
+4. Рекомендации The Zen of Python https://www.python.org/dev/peps/pep-0020/
+
+Разрешение конфликтов между руководствами производится по принципу деградации,
+т.е. если решение не было найдено в этом руководстве, то разработчик должен
+искать решение в первом документе вышеописанного списка, если решение не было
+найдено и там, то во втором документе и т.д. 
+
+Данное руководство носит рекомендательный характер, однако нарушение правил
+данного руководства может быть причиной отказа в слиянии веток git репозитория.
+
+Данное руководство может быть дополнено и расширено. Все изменения и правки
+вносятся только вместе с изменением версии данного руководства.
+
+Разработчики должны руководствоваться только самой последней версией данного
+руководства.
+
+Общие правила оформления кода
+-----------------------------
+
+Отступы
+^^^^^^^
+
+В качестве отступов разрешается использовать только 4 пробела.
+
+Максимальная длинна строки
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+79 символов с мягким ограничением до 100 символов, если абсолютно необходимо.
+Случаи выхода за пределы 79 символов должны маркироваться комментарием #noqa
+для поддержки валидации через Flake8. Хотя максимальная длина строки фактически
+устанавливается в 100 символов, разработчик должен пытаться уместить строку в
+79 символов разумно контроллируя вложенность и используя выражения
+continue, break, return.
+
+Перенос строк и длинных выражений
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+В случае необходимости разрешается перенос строк (string) с использованием
+тройных кавычек, если это не противоречит логике кода либо использование
+объявления строк в пределах круглых скобок, например:
+
+.. code:: python
+
+  variable = """Какая-нибудь очень длинная строка наделенная великим смыслом и
+                печеньками."""
+
+  variable = ("Какая-нибудь очень длинная строка наделенная великим смыслом и "
+              "печеньками.")
+
+при этом строки должны быть выравнены по левому краю, как показано выше.
+
+Для переноса длинных выражений не разрешается использовать backslash, кроме
+случаев когда необходимо описать RegExp выражение.
+
+Если требуется перенести вызов или описание функции, то нужно соблюдать
+выравнивание. Пример:
+
+.. code:: python
+
+  this_is_a_very_long(function_call, 'with many parameters', 23, 42,
+                      'and even more')
+
+В любом случае разработчику следует по возможности избегать создания методов
+с более чем пятью явно описанными параметрами.
+
+В случае если требуется описать список, который не помещается на одну строку,
+то следует делать перенос сразу после обяъвления списка. Пример:
+
+.. code:: python
+
+  very_long_list = [
+      "onelongitem", "twolongitems", "threelongitems", "fourlongitems",
+      "fivelongitems" 
+  ]
+
+В случае описания словарей, которые не помещаются в одну строку, лучше всего
+описывать словарь с учетом его структуры, помещая в каждую строку только одну
+пару ключ-значение. Пример:
+
+.. code:: python
+
+  very_long_dict = {
+      "hello": "world",
+      "some_internal_dict": {
+          "some": "key",
+          "another": "key" 
+      }
+  }
+
+Отступы между классами и функциями
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Функции и классы верхнего уровня разделяются между собой двумя строками, для
+всех остальных случаев разделение должно составлять одну строку. Логическое
+разделение кода внутри функции, разрешается, но лучше этим не злоупотреблять.
+
+
+Сравнения
+^^^^^^^^^
+
+Сравнения с boolean-типами и None должны производиться только с использованием
+"is" и "is not". При этом запрещается использование "not" отдельно от "is".
+Пример:
+
+.. code:: python
+
+  # Запрещается
+  if not some is True:
+      pass
+
+  # Разрешается
+  if some is not True:
+      pass
+
+Проверки вхождения элемента должны осуществляться с использованием "in" и
+"not in". При этом запрещается использование "not" отдельно от "in". Пример:
+
+.. code:: python
+
+  # Запрещается
+  if not some in all:
+      pass
+
+  # Разрешается
+  if some not in all:
+      pass
+
+Проверки типа объекта должны осуществляться только через функцию isinstance.
+Пример:
+
+.. code:: python
+
+  # Запрещается
+  check = type(variable) is SomeClass
+
+  # Разрешается
+  check = isinstance(variable, SomeClass)
+
+
+Именования
+^^^^^^^^^^
+
+Классы должны именоваться CamelCase'ом, т.е. каждое отдельное слово в имени
+класса должно начинаться с большой буквы. Пример:
+
+.. code:: python
+
+  class SomeInterestingClass:
+      pass
+  
+  class Some:
+      pass
+
+Аббревиатуры в наименовании классов пишутся большими буквами, например:
+
+.. code:: python
+
+  class SomeHTTPRequest:
+      pass
+
+Переменные, методы и функции именуются маленькими буквами с разделением слов
+через подчеркивание. Пример:
+
+.. code:: python
+
+  variable_name = "some text"
+
+  def some_method_or_function():
+      pass
+
+Константы именуются большими буквами с разделением слов подчеркиванием. Пример:
+
+.. code:: python
+
+  SOME_CONSTANT = "some text"
+
+В качестве первого аргумента в методы класса должен передаваться параметр
+"cls", в методы экземпляра класса - "self"
+
+Защищенные методы и переменные классов и их экземпляров, должны начинаться с
+одного нижнего подчеркивания.
+
+
+Lambda-функции
+^^^^^^^^^^^^^^
+
+Разрешены, но только в случаях когда они не требуют документирования и
+помещаются в одну строку.
+
+Документирование в коде
+-----------------------
+
+Язык
+^^^^
+
+Код который разрабатывается с проприетарной лицензией и если обратного не
+требует техническое задание документируется только на русском языке
+
+Формат
+^^^^^^
+
+Документирование в коде осуществляется при помощи линейных комментариев и
+docstring. Docstring должен быть совместим с системой документирования Sphinx
+и форматом reStructuredText. 
+
+Функции и методы
+^^^^^^^^^^^^^^^^
+
+Для функций и методов docstring должен начинаться на той же строке, что
+и открывающие кавычки. В случае, если комментарий не помещается в одну строку
+закрывающие кавычки должны находиться на отдельной строке. Пример:
+
+.. code:: python
+
+  def foo():
+      """Не выполняет ничего."""
+      pass
+  
+  
+  def bar():
+      """Не выполняет ничего и не делает вообще ничего, при условиях передачи
+      ничего, ничего не меняется.
+      """
+      pass
+
+В качестве описания функции и методов настоятельно рекомендуется использовать
+следующий шаблон описания:
+
+.. code:: python
+
+  def function(arg1, arg2, *args, **kwargs):
+      """<Краткое описание того что делает функция>.
+
+      <Детальное описание того что делает функция, возможно некоторых
+      особенностей использования функции которые желательно задокументировать>.
+
+      :param <тип аргумента, если применимо> arg1: Описание первого обязательного
+                                                   аргумента.
+      :param <тип аргумента, если применимо> arg2: Описание первого обязательного
+                                                   аргумента.
+      :param <тип аргумента, если применимо> in_kwargs: Описание необязательного
+                                                        аргумента.
+
+      :raises: Описание и условия для вызова исключений, которые могут быть
+               вызваны в функции.
+      :return: Описание возращаемого значния.
+
+
+      """
+      pass
+
+Модули
+^^^^^^
+
+Для кода который исполняется на python2 и python3 файл модуля должен начинаться
+со строки определяющей кодировку UTF-8:
+
+.. code:: python
+
+# -*- coding: utf-8 -*-
+
+Для кода который исполняется только на python3 использовать строку определяющую
+кодировку не нужно.
+
+Для модулей начальные и конечные кавычки docstring должны находиться на
+отдельных строках. Docstring модуля должен содержать путь до модуля и описание.
+Путь до модуля может не совпадать с фактическим применительно к модулям с
+тестами которые не импортируются.
+
+В качестве docstring модуля настоятельно рекомендуется использовать следующий
+шаблон описания:
+
+.. code:: python
+
+"""
+    path.to.module
+    ~~~~~~~~~~~~~~
+
+    Краткое описание назначения модуля.
+"""
+
+Комментарии
+^^^^^^^^^^^
+
+Линейные комментарии в коде должны находиться только над комментируемой
+строкой. После символа # должен ставиться пробел. В случаях описания атрибутов
+классов или их экземпляров допускается их описание через линейный комментарий.
+В этом случае комментарий должен начинаться с #: