Комментарий, дублирующий код

Пример того, как делать не надо:

add_to_list(books, extra_book) # добавим книгу в список

Этот комментарий # добавим книгу в список лишь пересказывает код. Всё то же самое можно узнать прочитав код: название функции add_to_list переводится как добавить в список, переменная books – книги, а extra_book – дополнительная книга. Не сложно догадаться, что вызов функции добавляет книгу extra_book в список книг books.

Ещё пример. Комментарий снова дублирует код:

counter += 1;  # увеличиваем счётчик на 1

Лишние комментарии загромождают код, в нём становится сложнее ориентироваться. Когда меняешь код, то приходится менять и комментарии, а это двойная работа.

Комментарий пишут, чтобы сообщить что-то новое и важное.

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

Чем меньше комментариев требует ваш код – тем лучше.

Docstring, дублирующий код

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

def count_characters_in_string(string):
     """Считает количество символов в строке"""

Docstring также должны сообщать что-то полезное и новое. В противном случае избавьтесь от них.