Самоучитель PythonВыпуск 2Дмитрий Мусинмая 07, 2017
 Скачать 0.74 Mb.
|
|
Пустые строки Отделяйте функции верхнего уровня и определения классов двумя пустыми строками. Определения методов внутри класса разделяются одной пустой строкой. Дополнительные пустые строки возможно использовать для разделения различных групп похожих функций. Пустые строки могут быть опущены между несколькими свя- занными однострочниками (например, набор фиктивных реализаций). Используйте пустые строки в функциях, чтобы указать логические разделы. Python расценивает символ control+L как незначащий (whitespace), и вы можете исполь- зовать его, потому что многие редакторы обрабатывают его как разрыв страницы — та- ким образом логические части в файле будут на разных страницах. Однако, не все редак- торы распознают control+L и могут на его месте отображать другой символ. 25.2. Внешний вид кода 85 Самоучитель Python, Выпуск 0.2 Кодировка исходного файла Кодировка Python должна быть UTF-8 (ASCII в Python 2). Файлы в ASCII (Python 2) или UTF-8 (Python 3) не должны иметь объявления кодировки. В стандартной библиотеке, нестандартные кодировки должны использоваться только для целей тестирования, либо когда комментарий или строка документации требует упо- мянуть имя автора, содержащего не ASCII символы; в остальных случаях использование \x, \u, \U или \N - наиболее предпочтительный способ включить не ASCII символы в стро- ковых литералах. Начиная с версии python 3.0 в стандартной библиотеке действует следующее соглаше- ние: все идентификаторы обязаны содержать только ASCII символы, и означать англий- ские слова везде, где это возможно (во многих случаях используются сокращения или неанглийские технические термины). Кроме того, строки и комментарии тоже должны содержать лишь ASCII символы. Исключения составляют: (а) test case, тестирующий не- ASCII особенности программы, и (б) имена авторов. Авторы, чьи имена основаны не на латинском алфавите, должны транслитерировать свои имена в латиницу. Проектам с открытым кодом для широкой аудитории также рекомендуется использовать это соглашение. Импорты • Каждый импорт, как правило, должен быть на отдельной строке. Правильно: import os import sys Неправильно: import sys , os В то же время, можно писать так: from subprocess import Popen, PIPE • Импорты всегда помещаются в начале файла, сразу после комментариев к модулю и строк документации, и перед объявлением констант. Импорты должны быть сгруппированы в следующем порядке: 1. импорты из стандартной библиотеки 2. импорты сторонних библиотек 3. импорты модулей текущего проекта Вставляйте пустую строку между каждой группой импортов. Указывайте спецификации __all__ после импортов. 25.2. Внешний вид кода 86 Самоучитель Python, Выпуск 0.2 • Рекомендуется абсолютное импортирование, так как оно обычно более читаемо и ведет себя лучше (или, по крайней мере, даёт понятные сообщения об ошибках) если импортируемая система настроена неправильно (например, когда каталог внутри пакета заканчивается на sys.path): import mypkg.sibling from mypkg import sibling from mypkg.sibling import example Тем не менее, явный относительный импорт является приемлемой альтернативой абсолютному импорту, особенно при работе со сложными пакетами, где использо- вание абсолютного импорта было бы излишне подробным: from import sibling from .sibling import example В стандартной библиотеке следует избегать сложной структуры пакетов и всегда ис- пользовать абсолютные импорты. Неявные относительно импорты никогда не должны быть использованы, и были удалены в Python 3. • Когда вы импортируете класс из модуля, вполне можно писать вот так: from myclass import MyClass from foo.bar.yourclass import YourClass Если такое написание вызывает конфликт имен, тогда пишите: import myclass import foo.bar.yourclass И используйте “myclass.MyClass” и “foo.bar.yourclass.YourClass”. • Шаблоны импортов (from import *) следует избегать, так как они делают неясным то, какие имена присутствуют в глобальном пространстве имён, что вводит в за- блуждение как читателей, так и многие автоматизированные средства. Существует один оправданный пример использования шаблона импорта, который заключается в опубликовании внутреннего интерфейса как часть общественного API (например, переписав реализацию на чистом Python в модуле акселератора (и не будет заранее известно, какие именно функции будут перезаписаны). Пробелы в выражениях и инструкциях Избегайте использования пробелов в следующих ситуациях: • Непосредственно внутри круглых, квадратных или фигурных скобок. Правильно: 25.3. Пробелы в выражениях и инструкциях 87 Самоучитель Python, Выпуск 0.2 spam(ham[ 1 ], {eggs: 2 }) Неправильно: spam( ham[ 1 ], { eggs: 2 } ) • Непосредственно перед запятой, точкой с запятой или двоеточием: Правильно: if x == 4 : (x, y); x, y = y, x Неправильно: if x == 4 : (x , y) ; x , y = y , x • Сразу перед открывающей скобкой, после которой начинается список аргументов при вызове функции: Правильно: spam( 1 ) Неправильно: spam ( 1 ) • Сразу перед открывающей скобкой, после которой следует индекс или срез: Правильно: dict [ 'key' ] = list [index] Неправильно: dict [ 'key' ] = list [index] • Использование более одного пробела вокруг оператора присваивания (или любого другого) для того, чтобы выровнять его с другим: Правильно: x = 1 y = 2 long_variable = 3 Неправильно: x = 1 y = 2 long_variable = 3 25.3. Пробелы в выражениях и инструкциях 88 Самоучитель Python, Выпуск 0.2 Другие рекомендации • Всегда окружайте эти бинарные операторы одним пробелом с каждой стороны: при- сваивания (=, +=, -= и другие), сравнения (==, <, >, !=, <>, <=, >=, in, not in, is, is not), логические (and, or, not). • Если используются операторы с разными приоритетами, попробуйте добавить про- белы вокруг операторов с самым низким приоритетом. Используйте свои собствен- ные суждения, однако, никогда не используйте более одного пробела, и всегда ис- пользуйте одинаковое количество пробелов по обе стороны бинарного оператора. Правильно: i = i + 1 submitted += 1 x = x * 2 - 1 hypot2 = x * x + y * y c = (a + b) * (a - b) Неправильно: i = i + 1 submitted += 1 x = x * 2 - 1 hypot2 = x * x + y * y c = (a + b) * (a - b) • Не используйте пробелы вокруг знака =, если он используется для обозначения име- нованного аргумента или значения параметров по умолчанию. Правильно: def complex (real, imag = 0.0 ): return magic(r = real, i = imag) Неправильно: def complex (real, imag = 0.0 ): return magic(r = real, i = imag) • Не используйте составные инструкции (несколько команд в одной строке). Правильно: if foo == 'blah' : do_blah_thing() do_one() do_two() do_three() Неправильно: 25.3. Пробелы в выражениях и инструкциях 89 Самоучитель Python, Выпуск 0.2 if foo == 'blah' : do_blah_thing() do_one(); do_two(); do_three() • Иногда можно писать тело циклов while, for или ветку if в той же строке, если коман- да короткая, но если команд несколько, никогда так не пишите. А также избегайте длинных строк! Точно неправильно: if foo == 'blah' : do_blah_thing() for x in lst: total += x while t < 10 : t = delay() Вероятно, неправильно: if foo == 'blah' : do_blah_thing() else : do_non_blah_thing() try : something() finally : cleanup() do_one(); do_two(); do_three(long, argument, list , like, this) if foo == 'blah' : one(); two(); three() Комментарии Комментарии, противоречащие коду, хуже, чем отсутствие комментариев. Всегда ис- правляйте комментарии, если меняете код! Комментарии должны являться законченными предложениями. Если комментарий — фраза или предложение, первое слово должно быть написано с большой буквы, если только это не имя переменной, которая начинается с маленькой буквы (никогда не из- меняйте регистр переменной!). Если комментарий короткий, можно опустить точку в конце предложения. Блок коммен- тариев обычно состоит из одного или более абзацев, составленных из полноценных пред- ложений, поэтому каждое предложение должно оканчиваться точкой. Ставьте два пробела после точки в конце предложения. Программисты, которые не говорят на английском языке, пожалуйста, пишите коммен- тарии на английском, если только вы не уверены на 120%, что ваш код никогда не будут читать люди, не знающие вашего родного языка. 25.4. Комментарии 90 Самоучитель Python, Выпуск 0.2 Блоки комментариев Блок комментариев обычно объясняет код (весь, или только некоторую часть), идущий после блока, и должен иметь тот же отступ, что и сам код. Каждая строчка такого бло- ка должна начинаться с символа # и одного пробела после него (если только сам текст комментария не имеет отступа). Абзацы внутри блока комментариев разделяются строкой, состоящей из одного символа #. “Встрочные” комментарии Старайтесь реже использовать подобные комментарии. Такой комментарий находится в той же строке, что и инструкция. “Встрочные” коммен- тарии должны отделяться по крайней мере двумя пробелами от инструкции. Они долж- ны начинаться с символа # и одного пробела. Комментарии в строке с кодом не нужны и только отвлекают от чтения, если они объяс- няют очевидное. Не пишите вот так: x = x + 1 # Increment x Впрочем, такие комментарии иногда полезны: x = x + 1 # Компенсация границы Строки документации • Пишите документацию для всех публичных модулей, функций, классов, методов. Строки документации необязательны для приватных методов, но лучше написать, что делает метод. Комментарий нужно писать после строки с def. • PEP 257 объясняет, как правильно и хорошо документировать. Заметьте, очень важ- но, чтобы закрывающие кавычки стояли на отдельной строке. А еще лучше, если перед ними будет ещё и пустая строка, например: """Return a foobang Optional plotz says to frobnicate the bizbaz first. """ • Для однострочной документации можно оставить закрывающие кавычки на той же строке. 25.4. Комментарии 91 Самоучитель Python, Выпуск 0.2 Контроль версий Если вам нужно использовать Subversion, CVS или RCS в ваших исходных кодах, делайте вот так: __version__ = "$Revision: 1a40d4eaa00b $" # $Source$ Вставляйте эти строки после документации модуля перед любым другим кодом и отде- ляйте их пустыми строками по одной до и после. Соглашения по именованию Соглашения по именованию переменных в python немного туманны, поэтому их список никогда не будет полным — тем не менее, ниже мы приводим список рекомендаций, дей- ствующих на данный момент. Новые модули и пакеты должны быть написаны согласно этим стандартам, но если в какой-либо уже существующей библиотеке эти правила на- рушаются, предпочтительнее писать в едином с ней стиле. Главный принцип Имена, которые видны пользователю как часть общественного API должны следовать конвенциям, которые отражают использование, а не реализацию. Описание: Стили имен Существует много разных стилей. Поможем вам распознать, какой стиль именования ис- пользуется, независимо от того, для чего он используется. Обычно различают следующие стили: • b (одиночная маленькая буква) • B (одиночная заглавная буква) • lowercase (слово в нижнем регистре) • lower_case_with_underscores (слова из маленьких букв с подчеркиваниями) • UPPERCASE (заглавные буквы) • UPPERCASE_WITH_UNDERSCORES (слова из заглавных букв с подчеркиваниями) • CapitalizedWords (слова с заглавными буквами, или CapWords, или CamelCase). Заме- чание: когда вы используете аббревиатуры в таком стиле, пишите все буквы аббре- виатуры заглавными — HTTPServerError лучше, чем HttpServerError. • mixedCase (отличается от CapitalizedWords тем, что первое слово начинается с ма- ленькой буквы) 25.5. Контроль версий 92 Самоучитель Python, Выпуск 0.2 • Capitalized_Words_With_Underscores (слова с заглавными буквами и подчеркивания- ми — уродливо!) Ещё существует стиль, в котором имена, принадлежащие одной логической группе, име- ют один короткий префикс. Этот стиль редко используется в python, но мы упоминаем его для полноты. Например, функция os.stat() возвращает кортеж, имена в котором традици- онно имеют вид st_mode, st_size, st_mtime и так далее. (Так сделано, чтобы подчеркнуть соответствие этих полей структуре системных вызовов POSIX, что помогает знакомым с ней программистам). В библиотеке X11 используется префикс Х для всех public-функций. В python этот стиль считается излишним, потому что перед полями и именами методов стоит имя объекта, а перед именами функций стоит имя модуля. В дополнение к этому, используются следующие специальные формы записи имен с до- бавлением символа подчеркивания в начало или конец имени: • _single_leading_underscore: слабый индикатор того, что имя используется для внут- ренних нужд. Например, from M import * не будет импортировать объекты, чьи име- на начинаются с символа подчеркивания. • single_trailing_underscore_: используется по соглашению для избежания конфликтов с ключевыми словами языка python, например: Tkinter Toplevel(master, class_ = 'ClassName' ) • __double_leading_underscore: изменяет имя атрибута класса, то есть в классе FooBar поле __boo становится _FooBar__boo. • __double_leading_and_trailing_underscore__ (двойное подчеркивание в начале и в кон- це имени): магические методы или атрибуты, которые находятся в пространствах имен, управляемых пользователем. Например, __init__, __import__ или __file__. Не изобретайте такие имена, используйте их только так, как написано в документа- ции. Предписания: соглашения по именованию Имена, которых следует избегать Никогда не используйте символы l (маленькая латинская буква «эль»), O (заглавная ла- тинская буква «о») или I (заглавная латинская буква «ай») как однобуквенные идентифи- каторы. В некоторых шрифтах эти символы неотличимы от цифры один и нуля. Если очень нуж- но l, пишите вместо неё заглавную L. Имена модулей и пакетов Модули должны иметь короткие имена, состоящие из маленьких букв. Можно использо- вать символы подчеркивания, если это улучшает читабельность. То же самое относится 25.6. Соглашения по именованию 93 Самоучитель Python, Выпуск 0.2 и к именам пакетов, однако в именах пакетов не рекомендуется использовать символ подчёркивания. Так как имена модулей отображаются в имена файлов, а некоторые файловые системы являются нечувствительными к регистру символов и обрезают длинные имена, очень важно использовать достаточно короткие имена модулей — это не проблема в Unix, но, возможно, код окажется непереносимым в старые версии Windows, Mac, или DOS. Когда модуль расширения, написанный на С или C++, имеет сопутствующий python- модуль (содержащий интерфейс высокого уровня), С/С++ модуль начинается с символа подчеркивания, например, _socket. Имена классов Имена классов должны обычно следовать соглашению CapWords. Вместо этого могут использоваться соглашения для именования функций, если интер- фейс документирован и используется в основном как функции. Обратите внимание, что существуют отдельные соглашения о встроенных именах: боль- шинство встроенных имен - одно слово (либо два слитно написанных слова), а соглаше- ние CapWords используется только для именования исключений и встроенных констант. Имена исключений Так как исключения являются классами, к исключениями применяется стиль именова- ния классов. Однако вы можете добавить Error в конце имени (если, конечно, исключе- ние действительно является ошибкой). Имена глобальных переменных Будем надеяться, что глобальные переменные используются только внутри одного моду- ля. Руководствуйтесь теми же соглашениями, что и для имен функций. Добавляйте в модули, которые написаны так, чтобы их использовали с помощью from M import *, механизм __all__, чтобы предотвратить экспортирование глобальных перемен- ных. Или же, используйте старое соглашение, добавляя перед именами таких глобаль- ных переменных один символ подчеркивания (которым вы можете обозначить те гло- бальные переменные, которые используются только внутри модуля). Имена функций Имена функций должны состоять из маленьких букв, а слова разделяться символами подчеркивания — это необходимо, чтобы увеличить читабельность. Стиль mixedCase допускается в тех местах, где уже преобладает такой стиль, для сохране- ния обратной совместимости. 25.6. Соглашения по именованию 94 Самоучитель Python, Выпуск 0.2 Аргументы функций и методов Всегда используйте self в качестве первого аргумента метода экземпляра объекта. Всегда используйте cls в качестве первого аргумента метода класса. Если имя аргумента конфликтует с зарезервированным ключевым словом python, обыч- но лучше добавить в конец имени символ подчеркивания, чем исказить написание слова или использовать аббревиатуру. Таким образом, class_ лучше, чем clss. (Возможно, хоро- шим вариантом будет подобрать синоним). Имена методов и переменных экземпляров классов Используйте тот же стиль, что и для имен функций: имена должны состоять из малень- ких букв, а слова разделяться символами подчеркивания. Используйте один символ подчёркивания перед именем для непубличных методов и ат- рибутов. Чтобы избежать конфликтов имен с подклассами, используйте два ведущих подчеркива- ния. Python искажает эти имена: если класс Foo имеет атрибут с именем __a, он не может быть доступен как Foo.__a. (Настойчивый пользователь все еще может получить доступ, вы- звав Foo._Foo__a.) Вообще, два ведущих подчеркивания должны использоваться только для того, чтобы избежать конфликтов имен с атрибутами классов, предназначенных для наследования. Примечание: есть некоторые разногласия по поводу использования __ имена (см. ниже). |