Этот проект не является официальным проектом Google, но был создан и поддерживается отечественными программистами на энтузиазме.
Если вы ищете официальную английскую версию от Google, посетитеGoogle Style Guide
В следующем кодеДаозначает «рекомендуется»,Нетозначает «не рекомендуется».
Точки с запятой
Не добавляйте точки с запятой в конце строк и не используйте точки с запятой, чтобы разместить две команды на одной строке.
Длина строки
Каждая строка не должна превышать 80 символов.
За исключением следующих случаев:
- Длинные инструкции импорта модулей
- URL-адреса в комментариях
Не используйте обратные слеши для объединения строк.
Python будетнеявно объединять строки внутри круглых, квадратных и фигурных скобокВы можете воспользоваться этой возможностью. При необходимости можно добавить дополнительную пару круглых скобок вокруг выражения.
推荐: foo_bar(self, width, height, color='black', design=None, x='foo',
emphasis=None, highlight=0)
if (width == 0 and height == 0 and
color == 'red' and emphasis == 'strong'):
Если текстовая строка не помещается в одну строку, можно использовать круглые скобки для неявного объединения строк:
x = ('这是一个非常长非常长非常长非常长 '
'非常长非常长非常长非常长非常长非常长的字符串')
В комментариях при необходимости размещайте длинные URL на одной строке.
Yes: # See details at
# http://www.example.com/us/developer/documentation/api/content/v2.0/csv_file_name_extension_full_specification.html
No: # See details at
# http://www.example.com/us/developer/documentation/api/content/\
# v2.0/csv_file_name_extension_full_specification.html
Обратите внимание на отступы элементов в примере выше; объяснение можно найти в разделе :ref:`отступы <indentation>` этого документа.
Круглые скобки
Используйте круглые скобки экономно.
Не используйте круглые скобки в операторах return или условных операторах, если только они не используются для объединения строк. Однако использование круглых скобок вокруг кортежей допустимо.
Yes: if foo:
bar()
while x:
x = bar()
if x and y:
bar()
if not x:
bar()
return foo
for (x, y) in dict.items(): ...
No: if (x):
bar()
if not(x):
bar()
return (foo)
Отступы
Используйте 4 пробела для отступа кода.
Никогда не используйте табуляцию и не смешивайте табуляцию и пробелы. Для объединения строк следует либо выравнивать переносимые элементы по вертикали (см. пример в разделе :ref:`длина строки <line_length>`), либо использовать висячий отступ в 4 пробела (в этом случае в первой строке не должно быть аргументов):
Yes: # 与起始变量对齐
foo = long_function_name(var_one, var_two,
var_three, var_four)
# 字典中与起始值对齐
foo = {
long_dictionary_key: value1 +
value2,
...
}
# 4 个空格缩进,第一行不需要
foo = long_function_name(
var_one, var_two, var_three,
var_four)
# 字典中 4 个空格缩进
foo = {
long_dictionary_key:
long_dictionary_value,
...
}
No: # 第一行有空格是禁止的
foo = long_function_name(var_one, var_two,
var_three, var_four)
# 2 个空格是禁止的
foo = long_function_name(
var_one, var_two, var_three,
var_four)
# 字典中没有处理缩进
foo = {
long_dictionary_key:
long_dictionary_value,
...
}
Пустые строки
Две пустые строки между определениями верхнего уровня, одна пустая строка между определениями методов.
Две пустые строки между определениями верхнего уровня, такими как определения функций или классов. Между определениями методов, а также между определением класса и его первым методом должна быть одна пустая строка. Внутри функции или метода добавляйте пустую строку там, где считаете уместным.
Пробельные символы
Следуйте стандартным типографским правилам расстановки пробелов вокруг знаков препинания.
Не ставьте пробелы внутри круглых скобок.
Следуйте стандартным типографским правилам расстановки пробелов вокруг знаков препинания.
Yes: spam(ham[1], {eggs: 2}, [])
No: spam( ham[ 1 ], { eggs: 2 }, [ ] )Не ставьте пробел перед запятыми, точками с запятой или двоеточиями, но ставьте пробел после них (кроме конца строки).
Yes: if x == 4:
print x, y
x, y = y, x
No: if x == 4 :
print x , y
x , y = y , x
Не ставьте пробел перед открывающей круглой скобкой списка параметров, индекса или среза.
Yes: spam(1)
no: spam (1)
Yes: dict['key'] = list[index]
No: dict ['key'] = list [index]
Ставьте пробел с обеих сторон бинарных операторов, таких как присваивание (=), сравнение (==, <, >, !=, <>, <=, >=, in, not in, is, is not) и логические (and, or, not). Что касается использования пробелов вокруг арифметических операторов, вам нужно самостоятельно принимать решение. Однако вы должны соблюдать единообразие с обеих сторон.
Yes: x == 1
No: x<1
Когда '=' используется для обозначения ключевого аргумента или значения параметра по умолчанию, не используйте пробелы ни с одной из сторон от него.
Yes: def complex(real, imag=0.0): return magic(r=real, i=imag)
No: def complex(real, imag = 0.0): return magic(r = real, i = imag)
Не используйте пробелы для вертикального выравнивания токенов в нескольких строках, потому что это становится бременем сопровождения (относится к :, #, = и т. д.):
Yes:
foo = 1000 # 注释
long_name = 2 # 注释不需要对齐
dictionary = {
"foo": 1,
"long_name": 2,
}
No:
foo = 1000 # 注释
long_name = 2 # 注释不需要对齐
dictionary = {
"foo" : 1,
"long_name": 2,
}
Шебанг
Большинству .py-файлов не требуется иметь #! в начале файла. СогласноPEP-394, главный файл программы должен начинаться с #!/usr/bin/python2 или #!/usr/bin/python3.
(Примечание переводчика: В информатике,Шебанг(также известный как хэшбанг) — это строка, состоящая из символа решётки и восклицательного знака (#!), которая представляет собой первые два символа первой строки текстового файла. Когда Шебанг присутствует в файле, загрузчик программ Unix-подобных операционных систем анализирует содержимое после Шебанга, рассматривает это содержимое как директиву интерпретатора, вызывает директиву и использует путь к файлу, содержащему Шебанг, в качестве аргумента интерпретатора. Например, файл, начинающийся с директивы #!/bin/sh, фактически вызовет программу /bin/sh при выполнении.)
#! изначально используется, чтобы помочь ядру найти интерпретатор Python, но он игнорируется при импорте модулей. Поэтому только файлы, которые выполняются напрямую, должны содержать #!.
Комментарии
Убедитесь, что для модулей, функций, методов и встроенных комментариев используется правильный стиль.
Строки документации
В Python есть уникальный способ комментирования: использование докстрингов. Докстринг — это первая инструкция в пакете, модуле, классе или функции. Эти строки можно автоматически извлечь через атрибут __doc__ объекта, и они используются pydoc. (Вы можете запустить pydoc для своего модуля, чтобы попробовать и посмотреть, как это выглядит). Наше соглашение для докстрингов — использовать тройные двойные кавычки """ (PEP-257). Докстринг должен быть организован следующим образом: сначала строка-резюме, заканчивающаяся точкой, вопросительным или восклицательным знаком (или докстринг состоит просто из одной строки). Затем пустая строка. Затем остальная часть докстринга, которая должна быть выровнена с первой кавычкой первой строки докстринга. Ниже приведены дополнительные спецификации форматирования для докстрингов.
Модули
Каждый файл должен содержать шаблон лицензии. Выберите подходящий шаблон в соответствии с лицензией, используемой проектом (например, Apache 2.0, BSD, LGPL, GPL).
Функции и методы
Под функциями, упоминаемыми ниже, понимаются функции, методы и генераторы.
Функция должна иметь докстринг, если только она не удовлетворяет следующим условиям:
- Не видна извне
- Очень короткая
- Простая и понятная
Докстринг должен содержать то, что делает функция, а также подробное описание входных и выходных данных. Обычно он не должен описывать «как это сделать», если только это не связано с какими-либо сложными алгоритмами. Докстринг должен предоставлять достаточно информации, чтобы, когда кто-то другой пишет код для вызова функции, ему не нужно было смотреть ни одну строку кода — только докстринг. Для сложного кода добавление комментариев рядом с кодом более осмысленно, чем использование докстринга.
Несколько аспектов функции должны быть задокументированы в определённых разделах, как описано ниже. Каждый раздел должен начинаться со строки заголовка. Строка заголовка заканчивается двоеточием. За исключением строки заголовка, остальная часть раздела должна иметь отступ в 2 пробела.
- Аргументы:
- Укажите имя каждого параметра, а после имени используйте двоеточие и пробел для отделения описания параметра. Если описание слишком длинное и превышает 80 символов в одной строке, используйте висячий отступ в 2 или 4 пробела (согласованно с остальным файлом). Описание должно включать требуемый тип и значение. Если функция принимает *foo (список аргументов переменной длины) или **bar (произвольные именованные аргументы), *foo и **bar должны быть перечислены подробно.
- Возвращает: (или Yields: для генераторов)
- Опишите тип и семантику возвращаемого значения. Если функция возвращает None, этот раздел можно опустить.
- Исключения:
- Перечислите все исключения, связанные с интерфейсом.
def fetch_bigtable_rows(big_table, keys, other_silly_variable=None): """Fetches rows from a Bigtable. Retrieves rows pertaining to the given keys from the Table instance represented by big_table. Silly things may happen if other_silly_variable is not None. Args: big_table: An open Bigtable Table instance. keys: A sequence of strings representing the key of each table row to fetch. other_silly_variable: Another optional variable, that has a much longer name than the other args, and which does nothing. Returns: A dict mapping keys to the corresponding table row data fetched. Each row is represented as a tuple of strings. For example: {'Serak': ('Rigel VII', 'Preparer'), 'Zim': ('Irk', 'Invader'), 'Lrrr': ('Omicron Persei 8', 'Emperor')} If a key from the keys argument is missing from the dictionary, then that row was not found in the table. Raises: IOError: An error occurred accessing the bigtable.Table object. """ pass
Класс
Класс должен иметь docstring ниже своего определения, описывающий класс. Если у вашего класса есть открытые атрибуты, документация должна содержать раздел Attributes. Он должен следовать тому же формату, что и параметры функции.
class SampleClass(object): """Summary of class here. Longer class information.... Longer class information.... Attributes: likes_spam: A boolean indicating if we like SPAM or not. eggs: An integer count of the eggs we have laid. """ def __init__(self, likes_spam=False): """Inits SampleClass with blah.""" self.likes_spam = likes_spam self.eggs = 0 def public_method(self): """Performs operation blah."""
Блочные комментарии и встроенные комментарии
Код, который больше всего нуждается в комментариях, — это сложные места. Если вамна код-ревьюприходится это объяснять, то сейчас следует написать для него комментарий. Для сложных операций напишите несколько строк комментариев перед началом операции. Для кода, который неочевиден с первого взгляда, добавьте комментарий в конце строки.
# We use a weighted dictionary search to find out where i is in # the array. We extrapolate position based on the largest num # in the array and the array size and then do binary search to # get the exact number. if i & (i-1) == 0: # true iff i is a power of 2Для улучшения читаемости комментарии должны быть отделены от кода как минимум 2 пробелами.
С другой стороны, никогда не описывайте код. Предполагайте, что человек, читающий код, знает Python лучше вас; он просто не знает, что должен делать ваш код.
# BAD COMMENT: Now go through the b array and make sure whenever i occurs # the next element is i+1
Класс
Если класс не наследуется от других классов, явно наследуйте его от object. То же самое относится к вложенным классам.
Yes: class SampleClass(object):
pass
class OuterClass(object):
class InnerClass(object):
pass
class ChildClass(ParentClass):
"""Explicitly inherits from another class already."""
No: class SampleClass:
pass
class OuterClass:
class InnerClass:
pass
Наследование отobjectзаключается в том, чтобы свойства работали правильно, и это защищает ваш код от особой потенциальной несовместимости в Python 3000. Это также определяет некоторые специальные методы, реализующие семантику объектов по умолчанию, включая__new__, __init__, __delattr__, __getattribute__, __setattr__, __hash__, __repr__, and __str__ .
Строки
Yes: x = a + b
x = '%s, %s!' % (imperative, expletive)
x = '{}, {}!'.format(imperative, expletive)
x = 'name: %s; score: %d' % (name, n)
x = 'name: {}; score: {}'.format(name, n)
No: x = '%s%s' % (a, b) # use + in this case
x = '{}{}'.format(a, b) # use + in this case
x = imperative + ', ' + expletive + '!'
x = 'name: ' + name + '; score: ' + str(n)
Избегайте использования операторов + и += для накопления строк в цикле. Поскольку строки неизменяемы, это создаёт ненужные временные объекты и приводит к квадратичному, а не линейному времени выполнения. В качестве альтернативы можно добавлять каждую подстроку в список, а затем после завершения цикла использовать.joinдля объединения списка. (Также можно записывать каждую подстроку вcStringIO.StringIOбуфер.)
Yes: items = ['<table>']
for last_name, first_name in employee_list:
items.append('<tr><td>%s, %s</td></tr>' % (last_name, first_name))
items.append('</table>')
employee_table = ''.join(items)
No: employee_table = '<table>'
for last_name, first_name in employee_list:
employee_table += '<tr><td>%s, %s</td></tr>' % (last_name, first_name)
employee_table += '</table>'
В одном и том же файле соблюдайте единообразие в использовании кавычек для строк. Используйте либо одинарные кавычки ', либо двойные кавычки " для строк и придерживайтесь этого в одном файле. Вы можете использовать другой вид кавычек внутри строки, чтобы избежать необходимости экранировать её. PyLint уже добавил эту проверку.
Yes:
Python('Why are you hiding your eyes?')
Gollum("I'm scared of lint errors.")
Narrator('"Good!" thought a happy Python reviewer.')
No:
Python("Why are you hiding your eyes?")
Gollum('The lint. It burns. It burns us.')
Gollum("Always the great lint. Watching. Watching.")
Используйте тройные двойные кавычки """ для многострочных строк вместо тройных одинарных кавычек '''. Только если проект использует одинарные кавычки ' для строк, можно использовать тройные ''' для многострочных строк, не являющихся строками документации. Строки документации должны использовать тройные двойные кавычки """. Однако учтите, что неявная конкатенация строк обычно яснее, потому что многострочные строки не выравниваются по отступам остальной программы.
Yes:
print ("This is much nicer.\n"
"Do it this way.\n")
No:
print """This is pretty ugly.
Don't do this.
"""
Файлы и сокеты
Явно закрывайте файлы и сокеты, когда они больше не нужны.
Оставление файлов, сокетов или других файлоподобных объектов открытыми без необходимости имеет множество побочных эффектов, например:
- Они могут потреблять ограниченные системные ресурсы, такие как файловые дескрипторы. Если эти ресурсы не возвращаются системе своевременно после использования, код, работающий с этими объектами, исчерпает их.
- Удержание файлов открытыми может препятствовать другим операциям с этими файлами, таким как перемещение или удаление.
- Просто логическое закрытие файлов и сокетов всё ещё оставляет их открытыми для непреднамеренного чтения или записи программами, которые совместно их используют. Только когда они действительно закрыты, попытки чтения или записи вызовут исключения, благодаря чему проблемы быстро проявятся.
Более того, идея о том, что файлы и сокеты будут автоматически закрываться при уничтожении файловых объектов, — попытка привязать время жизни файловых объектов к состоянию файлов, — нереалистична. По следующим причинам:
- Нет способа гарантировать, что среда выполнения действительно вызовет деструктор файла. Разные реализации Python используют разные методы управления памятью, например отложенную сборку мусора. Отложенная сборка мусора может приводить к тому, что время жизни объектов произвольно и неограниченно продлевается.
- Неожиданные ссылки на файлы могут приводить к тому, что файлы удерживаются дольше, чем ожидалось (например, в трассировках исключений, включающих глобальные переменные, и т. п.).
Рекомендуется использоватьоператор "with"для управления файлами:
with open("hello.txt") as hello_file:
for line in hello_file:
print line
Для файлоподобных объектов, которые не поддерживают оператор "with", используйте contextlib.closing():
import contextlib
with contextlib.closing(urllib.urlopen("http://www.python.org/")) as front_page:
for line in front_page:
print line
Устаревший код AppEngine Python 2.5, использующий оператор "with", требует добавления "from __future__ import with_statement".
Комментарии TODO
Используйте комментарии TODO для временного кода как краткосрочное решение. Не идеально, но достаточно хорошо.
Комментарии TODO должны содержать строку "TODO" в самом начале, за которой следует ваше имя, адрес электронной почты или другой идентификатор в круглых скобках. Затем необязательное двоеточие. После этого должна быть строка комментария, объясняющая, что нужно сделать. Основная цель — иметь единый формат TODO, чтобы можно было найти человека, добавившего комментарий (и при необходимости он мог предоставить больше деталей). Написание комментария TODO не гарантирует, что автор лично исправит проблему. Когда вы пишете TODO, пожалуйста, указывайте своё имя.
# TODO(kl@gmail.com): Use a "*" here for string repetition. # TODO(Zeke) Change this to use relations.
Если ваш TODO имеет форму "сделать что-то в будущем", обязательно укажите конкретную дату ("исправить в ноябре 2009 года") или конкретное событие ("удалить этот код, когда все клиенты смогут обрабатывать XML-запросы").
Формат импорта
Каждый импорт должен быть на отдельной строке
Yes: import os
import sys
No: import os, sys
Импорты всегда должны располагаться в верхней части файла, после комментариев к модулю и docstrings, и перед глобальными переменными и константами модуля. Импорты следует группировать от наиболее общих к наименее общим:
- Импорты стандартной библиотеки
- Импорты сторонних библиотек
- Импорты, специфичные для приложения
Внутри каждой группы импорты должны быть отсортированы лексикографически по полному пути пакета каждого модуля без учёта регистра.
import foo from foo import bar from foo.bar import baz from foo.bar import Quux from Foob import ar
Утверждения
Как правило, каждый оператор должен находиться на отдельной строке
Однако, если проверка и результат помещаются в одной строке, вы также можете разместить их в одной строке. В случае оператора if вы можете делать это только при отсутствии else. В частности, никогда не делайте этого сtry/exceptделать это, потому что try и except нельзя размещать в одной строке.
Yes: if foo: bar(foo)
No:
if foo: bar(foo)
else: baz(foo)
try: bar(foo)
except ValueError: baz(foo)
try:
bar(foo)
except ValueError: baz(foo)
Управление доступом
В Python для тривиальных и неважных функций доступа вместо этого следует напрямую использовать публичные переменные, чтобы избежать дополнительных накладных расходов на вызов функций. При добавлении дополнительной функциональности вы можете использовать свойства для поддержания синтаксической согласованности.
(Примечание переводчика: объектно-ориентированные программисты, ценящие инкапсуляцию, могут быть оскорблены этим, потому что им всегда говорили, что все переменные-члены должны быть приватными! На самом деле это действительно хлопотно. Постарайтесь принять философию Python.)
С другой стороны, если доступ сложнее или накладные расходы на доступ к переменной значительны, следует использовать что-то вродеget_foo()иset_foo()вызовов функций. Если предыдущее поведение кода допускало доступ через свойства, то не привязывайте новые функции доступа к свойству. Так любой код, который пытается получить доступ к переменной старым способом, не сработает, и пользователи поймут, что сложность изменилась.
Чтобы задать имя ограничения UNIQUE и применить его к нескольким столбцам, можно использовать следующий синтаксис:
module_name, package_name, ClassName, method_name, ExceptionName, function_name, GLOBAL_VAR_NAME, instance_var_name, function_parameter_name, local_var_name.
Имена, которых следует избегать
- Односимвольные имена, кроме счётчиков и итераторов.
- Дефисы (-) в именах пакетов/модулей
- Имена, которые начинаются и заканчиваются двойными подчёркиваниями (зарезервированы Python, например, __init__)
Соглашения об именовании
- Так называемый «Внутренний» означает, что доступ возможен только внутри модуля или, внутри класса, он является защищённым или приватным.
- Ведущий одиночный символ подчёркивания (_) указывает, что переменная или функция модуля является защищённой (не включается при использовании import * from).
- Переменные экземпляра или методы, начинающиеся с двойных подчёркиваний (__), являются приватными для класса.
- Помещайте связанные классы и функции верхнего уровня в один модуль. В отличие от Java, нет необходимости ограничивать один класс на модуль.
- Используйте слова с заглавной буквы для имён классов (например, CapWords, т. е. стиль Pascal), но имена модулей должны использовать нижний регистр с подчёркиваниями (например, lower_with_under.py). Хотя многие существующие модули используют имена вроде CapWords.py, сейчас это не рекомендуется, потому что может вводить в заблуждение, если имя модуля случайно совпадает с именем класса.
Спецификации, рекомендованные отцом Python, Гвидо
| Type | Public | Внутренний |
|---|---|---|
| Модули | lower_with_under | _lower_with_under |
| Пакеты | lower_with_under | |
| Классы | CapWords | _CapWords |
| Исключения | CapWords | |
| Функции | lower_with_under() | _lower_with_under() |
| Глобальные/классовые константы | CAPS_WITH_UNDER | _CAPS_WITH_UNDER |
| Глобальные/классовые переменные | lower_with_under | _lower_with_under |
| Переменные экземпляра | lower_with_under | _lower_with_under (защищённый) или __lower_with_under (приватный) |
| Имена методов | lower_with_under() | _lower_with_under() (защищённый) или __lower_with_under() (приватный) |
| Параметры функций/методов | lower_with_under | |
| Локальные переменные | lower_with_under |
Main
Даже файл, предназначенный для использования в качестве скрипта, должен быть импортируемым. И простой import не должен приводить к выполнению основной функциональности скрипта, так как это побочный эффект. Основную функциональность следует размещать в функции main().
В Python pydoc и юнит-тесты требуют, чтобы модули были импортируемыми. Ваш код всегда должен выполнять проверку перед запуском основной программыif __name__ == '__main__', чтобы основная программа не выполнялась при импорте модуля.
def main():
...
if __name__ == '__main__':
main()
Весь код верхнего уровня выполняется при импорте модуля. Будьте осторожны: не вызывайте функции, не создавайте объекты и не выполняйте операции, которые не должны выполняться при использовании pydoc.