• Строка документации для отдельной программы должна объяснять используемые ею ключи, назначение аргументов и переменных среды и другую подобную информацию.
• Для строк документации рекомендуется везде использовать утроенные кавычки (>""").
• Однострочная документация пишется в императиве, как команда: «делай это», «возвращай то».
• Многострочная документация содержит расширенное описание модуля, функции, класса. Она будет смотреться лучше, если текст будет написан с тем же отступом, что и начало строки документации.
• Документация для модуля должна перечислять экспортируемые функции, классы, исключения и другие объекты, по одной строке на объект.
• Строка документации для функции или метода должна кратко описывать действия функции, ее входные параметры и возвращаемое значение, побочные эффекты и возможные исключения (если таковые есть). Должны быть обозначены необязательные аргументы и аргументы, не являющиеся частью интерфейса.
• Документация для класса должна перечислять общедоступные методы и атрибуты, содержать рекомендации по применению класса в качестве базового для других классов. Если класс является подклассом, необходимо указать, какие методы полностью заменяют, перегружают, а какие используют, но расширяют соответствующие методы надкласса. Необходимо указать и другие изменения по сравнению с надклассом.
• Контроль версий повышает качество процесса создания программного обеспечения. Для этих целей часто используются RCS или CVS. «Python Style Guide» рекомендует записывать >$Revision: 1.31 $ в переменную с именем >__version__, а другие данные заключать в комментарии ">#".
Сегодня сосуществуют несколько более или менее широко распространенных правил именования объектов. Программисты вольны выбрать тот, который принят в их организации или конкретном проекте. Автор Python рекомендует придерживаться нижеследующих правил для именования различных объектов, с тем чтобы это было понятно любому программисту, использующему Python.
• Имена модулей лучше давать строчными буквами, например, >shelve, >string, либо делать первые буквы слов прописными, >StringIO, >UserDict. Имена написанных на C модулей расширения обычно начинаются с подчеркивания ">_", а соответствующие им высокоуровневые обертки — с прописных букв: >_tkinter и >Tkinter.
• Ключевые слова нельзя использовать в качестве имен, однако, если все–таки необходимо воспользоваться этим именем, стоит добавить одиночное подчеркивание в конце имени. Например: >class_.
• Классы обычно называют, выделяя первые буквы слов прописными, как в