Физтех.Статистика
Скачать ipynb
Введение в анализ данных¶
Линтеры¶
Стиль кода является довольно важной вещью для соблюдения. Например, именно стиль кода помогает в командной работе, способствует более лёгкому чтению кода, важность чего возрастает по мере присоединения новых участников к команде. Для Python стандартом является PEP 8, более полную и официальную информацию можно прочитать здесь: https://peps.python.org/pep-0008/.
Перечислим кратко основные правила, которые касаются оформления кода на нашем курсе:
- Отступы составляют ровно 4 пробела, табуляции не используются. К слову, в Питоне нет ключевых слов по типу
{и}в C иbeginиendв Паскале. Блоки кода разделяются пробелами. - Все переменные должны иметь понятные названия и состоять только из строчных букв. Например, вместо того, чтобы назвать выборку как
X, лучше назвать ееsample. В качестве разделителей используйте подчеркивания. В редких случаях можно и отступать от этого правила, если обозначения понятны из решаемой задачи. - Вокруг всех знаков арифметических операций, присваивания и пр. обязательны пробелы с двух сторон. Исключение — запись вида
a=bв аргументах функции. Примеры будут далее. - Разделяйте логические куски программы пустыми строками. Вряд ли вы сможете написать код строк на 10-15, в который нельзя вставить ни одну пустую строку, разделяющую код на логические части. Перед всеми логическими кусками кода должен быть комментарий к этому куску кода.
- Все функции (кроме самых маленьких) должны содержать подробную документацию, написанную по правилам оформления документаций.
- Если комментарий дается на строке с кодом, то оформить его стоит так:
код [ровно 2 пробела] # [ровно 1 пробел] комментарий
- Если комментарий дается на отдельной строке, то он должен иметь тот же отступ, что и строка кода под ним. Скорее всего перед таким комментарием можно вставить пустую строку.
- Не нужно комментировать очевидное.
- Крайне важно: не нужно писать весь код в одной ячейке ноутбука!
- Не стоит создавать вермишель ячеек — несколько подряд идущих ячеек с 1-3 строками кода, если в этом нет необходимости.
- Если есть возможность, при выводе десятичных чисел следует оставлять разумное число знаков после запятой.
Отдельно стоит отметить, что код должен быть понятен проверяющему. В частности, должны использоваться понятные названия переменных и присутствовать подробные комментарии. Если проверяющий не поймет код, оценка за задание может быть снижена.
Кроме того, все ноутбуки, которые присылаются в бот, проходят проверку линтером. С помощью линтера происходит статический анализ кода на предмет соответствия стилю кода. Линтеры крайне полезны в командной работе, особенно в больших компаниях. В части компаний код не сможет пойти в «прод», если он не пройдёт проверку линтером.
Одним из популярных средств для этого является Black. Чтобы с помощью него можно было проверять ноутбуки, его нужно устанавливать следующим образом: pip install "black[jupyter]".
После установки можно реформатировать ноутбуки, например, black test.ipynb -l 80. Можно указывать параметры командной строки:
-l,--line-length— максимальная длина строки (по умолчанию 88)--diff— позволяет увидеть возможные изм енения после применения-v,--verbose— показывает подробные сообщения, связанные с ходом работы линтера
Более подробно можно посмотреть в документации.
Кроме того, с помощью комментариев вида # fmt: skip (для отдельных строк), а также # fmt: off в начале и # fmt: on в конце (для блока подряд идущих строк) можно защитить нужные строки кода от реформатирования. Можно смешивать с другими комментариями: например, # fmt: skip # pylint # noqa.
Линтер Black поддерживает интеграцию с такиими известными средами разработки, как Vim, Visual Studio Code и другие. Подробнее можно посмотреть в https://black.readthedocs.io/en/stable/integrations/editors.html.
Рассмотрим примеры, как работает Black.
1. Пробелы и переносы строк¶
Black исправляет горизонтальные пробелы так, чтобы это было совместимо с pycodestyle. Лучший сценарий для работы с переносами строк заключается в том, что выражение после исправления помещается в одну строку с учётом ограничения на её длину.
# fmt: off
j = [1,
2,
3
]
# fmt: on
j = [1, 2, 3]
Если это не представляется возможным, то Black ищет пары открывающей и закрывающей скобок (в приоритете внешние) и смотрит, возможен ли предыдущий сценарий с выражением внутри скобок.
# fmt: off
ImportantClass.important_method(exc, limit, lookup_lines, capture_locals, extra_argument)
# fmt: on
ImportantClass.important_method(
exc, limit, lookup_lines, capture_locals, extra_argument
)
Если невозможно с одной парой скобок, то выбирается следующая. Элементы, разделённые запятыми, Black старается сохранить на одной строке. Если и это невозможно, то Black выносит каждый из этих элементов на отдельную строку.
# fmt: off
def very_important_function(template: str, *variables, file: os.PathLike, engine: str, header: bool = True, debug: bool = False):
"""Applies `variables` to the `template` and writes to `file`."""
with open(file, 'w') as f:
...
# fmt: on
def very_important_function(
template: str,
*variables,
file: os.PathLike,
engine: str,
header: bool = True,
debug: bool = False,
):
"""Applies `variables` to the `template` and writes to `file`."""
with open(file, "w") as f:
...
2. Приоритеты символов¶
Для Black предпочтительнее использовать скобки, чем обратные косые черты (backslashes), которые при обработке Black удаляются.
# fmt: off
if some_short_rule1 \
and some_short_rule2:
...
# fmt: on
if some_short_rule1 and some_short_rule2:
...
# fmt: off
if some_long_rule1 \
and some_long_rule2:
...
# fmt: on
if some_long_rule1 and some_long_rule2:
...
3. Иные свойства¶
Кроме того, Black позволяет более экономно использовать пустые строки, например:
# fmt: off
def foo():
print("All the newlines above me should be deleted!")
if condition:
print("No newline above me!")
print("There is a newline above me, and that's OK!")
class Point:
x: int
y: int
# fmt: on
def foo():
print("All the newlines above me should be deleted!")
if condition:
print("No newline above me!")
print("There is a newline above me, and that's OK!")
class Point:
x: int
y: int
Black соблюдает правила, связанные с комментариями, например:
код [ровно 2 пробела] # [ровно 1 пробел] комментарий.
Для Black предпочтительнее двойные кавычки, чем одинарные. Кроме того, соблюдаются правила про пробелы вокруг операторов.
4. Задание¶
Время экспериментов!
- Напишите произвольный код на Python, содержащий скобки, арифметические операторы, кавычки, пустые строки и всё остальное, что вы захотите.
- Сохраните либо код, либо ноутбук в отдельный файл:
test.py,test.ipynb. - Запустите Black:
black test.py. Какие изменения вы можете заметить?
