Посты с тэгом правила кодирования


Стиль кода в Python: Part 2

Комментарии

Комментарии, которые противоречат коду, хуже, чем отсутствие комментариев. Всегда исправляйте комментарии, если меняете код!

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

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

Ставьте два пробела после точки в конце предложения.

Если вы пишете по-английски, не забывайте о Странке и Уайте (имеется в виду книга Strunk & White, “Elements of style”, которая является практически эталонным руководством по правильному написанию текстов на английском языке, —



Стиль кода в Python: Part 1

Введение

Этот документ описывает соглашение о том, как писать код для языка python, включая стандартную библиотеку, входящую в состав python. Пожалуйста, посмотрите также на сопутствующий PEP (python enhanced proposal — заявки на улучшение языка python), описывающий, какого стиля следует придерживаться при написании кода на C в реализации языка python1.

Этот документ создан на основе рекомендаций Гуидо ван Россума с добавлениями от Барри. Если где-то возникал конфликт, мы выбирали стиль Гуидо. И, конечно, этот PEP может быть неполным (фактически, он, наверное, никогда не будет закончен).

A Foolish Consistency is the Hobgoblin of Little Minds2

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