Руководство по стилю¶Style Guide

Документация Python должна следовать Apple Publications Style Guide везде, где это возможно. Это руководство по стилю было выбрано в основном потому, что оно кажется разумным и легко доступно онлайн.

Темы, не освещённые в руководстве по стилю Apple, будут рассмотрены в этом документе.

Все файлы reST используют отступ в 3 пробела. Максимальная длина строки – 80 символов для обычного текста, но таблицы, примеры кода с глубокими отступами и длинные ссылки могут выходить за этот предел.

Активно используйте пустые строки, где это уместно; они помогают группировать связанные элементы.

После точки в конце предложения может следовать один или два пробела; хотя reST игнорирует второй пробел, некоторые пользователи по традиции его ставят, например, для поддержки режима авто-заполнения Emacs.

Сноски, как правило, не приветствуются, хотя они могут использоваться, когда являются лучшим способом представления конкретной информации. Когда ссылка на сноску добавляется в конце предложения, она должна следовать за знаком препинания, завершающим предложение. Разметка reST должна выглядеть примерно так:

This sentence has a footnote reference. [#]_ This is the next sentence.

Сноски должны быть собраны в конце файла, или, если файл очень длинный, в конце раздела. Docutils автоматически создаст обратные ссылки на ссылку на сноску.

Сноски могут появляться в середине предложений, если это уместно.

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

Другие термины и слова также заслуживают особого упоминания; эти соглашения следует использовать для обеспечения единообразия во всей документации:

CPU

Расшифровывается как «central processing unit». Многие руководства по стилю рекомендуют раскрывать аббревиатуру при первом использовании (и если вы всё же используете её, делайте это!). Для документации Python эту аббревиатуру следует избегать, так как нет разумного способа предсказать, какое вхождение читатель увидит первым. Лучше использовать слово «процессор».

POSIX

Название, присвоенное определённой группе стандартов. Всегда пишется заглавными буквами.

Python

Название нашего любимого языка программирования всегда пишется с заглавной буквы.

Unicode

Название набора символов и соответствующей кодировки. Всегда пишется с заглавной буквы.

Unix

Название операционной системы, разработанной в AT&T Bell Labs в начале 1970-х годов.