Роман Сузи - Язык программирования Python

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

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

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

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

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

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

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

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

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

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

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

• Контроль версий повышает качество процесса создания программного обеспечения. Для этих целей часто используются RCS или CVS. «Python Style Guide» рекомендует записывать $Revision: 1.31 $в переменную с именем __version__, а другие данные заключать в комментарии " #".

Сегодня сосуществуют несколько более или менее широко распространенных правил именования объектов. Программисты вольны выбрать тот, который принят в их организации или конкретном проекте. Автор Python рекомендует придерживаться нижеследующих правил для именования различных объектов, с тем чтобы это было понятно любому программисту, использующему Python.

• Имена модулей лучше давать строчными буквами, например, shelve, string, либо делать первые буквы слов прописными, StringIO, UserDict. Имена написанных на C модулей расширения обычно начинаются с подчеркивания " _", а соответствующие им высокоуровневые обертки — с прописных букв: _tkinterи Tkinter.

• Ключевые слова нельзя использовать в качестве имен, однако, если все–таки необходимо воспользоваться этим именем, стоит добавить одиночное подчеркивание в конце имени. Например: class_.

• Классы обычно называют, выделяя первые буквы слов прописными, как в Tagили HTTPServer.

• Имена исключений обычно содержат в своем составе слово «error» (или «warning»). Встроенные модули пишут это слово со строчной буквы (как os.error) (но могут писать и с прописной): distutils.DistutilsModuleError.

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

• Имена глобальных переменных (если таковые используются) лучше начинать с подчеркивания, чтобы они не импортировались из модуля оператором from–importсо звездочкой.

• Имена методов записываются по тем же правилам, что и имена функций.

• Имена констант (имен, которые не должны переопределяться) лучше записывать прописными буквами, например: RED, GREEN, BLUE.

• При работе с языком Python необходимо учитывать, что интерпретатор считает некоторые классы имен специальными (обычно такие имена начинаются с подчеркивания).

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