28.12.2024 09:38
jetbird1 0 23 Источник

Данный инструмент появился в результате попытки сэкономить время в процессе код-ревью, когда часть усилий тратилась на исправление какие-то незначительных, но тем не менее бросающихся в глаза артефактов, связанных с форматированием комментариев.

Понятно, что эта тема гораздо шире, т.к. есть различные форматы многострочных комментариев в стиле PEP 257 или Sphinx, ну а в этот линтер вошли только наиболее часто встречающиеся случаи, связанные с написанием комментариев после решетки '#', с которыми пришлось сталкиваться в работе мне лично.

Линтер может быть полезен как сам по себе либо как пример того, как можно автоматизировать проверки по согласованному стилю оформления кода.

Что линтер посчитает "правильным"

Однострочный комментарий начинается с заглавной буквы и отделяется от решетки пробелом:

# Comment above the code
my_func()

Комментарий после строки кода отделяется двумя пробелами:

my_func()  # comment after the code

Многострочный комментарий начинается с заглавной буквы (следующие строки - не обязательно):

# Multi-line comment must start with an uppercase and
# can follow with a lowercase letter.

Из этого правила допускаются такие исключения как HTTP/HTTPS ссылки:

# http://gitlab.com/krash/python-checker

разнообразные исключения для линтеров или mypy:

# noqa: D103
# type: ignore

а также TODO, NOTE и, конечно, sbebang:

#!/usr/bin/python
# NOTE someting important for other developers
# TODO a task description

Что не обрадует линтер

Отсутствие пробелов после решетки:

#comment should have a space after the hash symbol.

Отсутствие пробелов после одной из решеток в многострочных комментариях:

# Multi-line comment should also contain spaces
#after the hash symbol in all of its lines.

Излишние пробелы после решетки:

#     Too much spaces after the hash symbol

Однострочный комментарий, начинающийся со строчной буквы:

# this one-line comment starts with a lowercase letter.

Пустой комментарий:

#

Как использовать

Добавляем в конфигурацию .pre-commit-config.yaml проекта на Python следующий код:

  - repo: http://gitlab.com/krash/python-checker
    rev: v0.0.7
    hooks:
      - id: python-check

Не забываем добавить изменения в .pre-commit-config.yaml в индекс GIT:

git add .pre-commit-config.yaml

Теперь можно запускать проверку кода:

pre-commit run python-check -a

Комментарии (0)