Читать «Язык программирования Python» онлайн - страница 14

• Также рекомендуется применение одиночных пробелов вокруг низкоприоритетных операций сравнения и оператора присваивания. Пробелы вокруг более приоритетных операций ставятся в равном количестве слева и справа от знака операции.

Несколько рекомендаций касаются написания комментариев.

• Комментарии должны точно отражать актуальное состояние кода. (Поддержание актуальных комментариев должно быть приоритетной задачей!) После коротких комментариев можно не ставить точку, тогда как длинные лучше писать по правилам написания текста. Автор Python обращается к неанглоязычным программистам с просьбой писать комментарии на английском, если есть хотя бы небольшая вероятность того, что код будут читать специалисты, говорящие на других языках.

• Комментарии к фрагменту кода следует писать с тем же отступом, что и комментируемый код. После "#" должен идти одиночный пробел. Абзацы можно отделять строкой с "#" на том же уровне. Блочный комментарий можно отделить пустыми строками от окружающего кода.

• Комментарии, относящиеся к конкретной строке, не следует использовать часто. Символ "#" должен отстоять от комментируемого оператора как минимум на два пробела.

• Хороший комментарий не перефразирует программу, а содержит дополнительную информацию о действии программы в терминах предметной области.

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

• Строка документации для отдельной программы должна объяснять используемые ею ключи, назначение аргументов и переменных среды и другую подобную информацию.

• Для строк документации рекомендуется везде использовать утроенные кавычки (""").

• Однострочная документация пишется в императиве, как команда: «делай это», «возвращай то».

• Многострочная документация содержит расширенное описание модуля, функции, класса. Она будет смотреться лучше, если текст будет написан с тем же отступом, что и начало строки документации.

• Документация для модуля должна перечислять экспортируемые функции, классы, исключения и другие объекты, по одной строке на объект.

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

• Документация для класса должна перечислять общедоступные методы и атрибуты, содержать рекомендации по применению класса в качестве базового для других классов. Если класс является подклассом, необходимо указать, какие методы полностью заменяют, перегружают, а какие используют, но расширяют соответствующие методы надкласса. Необходимо указать и другие изменения по сравнению с надклассом.