|
⇤ ← Revision 1 as of 2005-06-10 06:30:58
Size: 35066
Comment:
|
Size: 23154
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 14: | Line 14: |
| 原文:[wiki:epes/pep-0008.html Style Guide for Python Code] | 原文:'''[wiki:epes/pep-0008.html PEP 008]'''《Style Guide for Python Code》 |
| Line 174: | Line 174: |
| == 表达式和语句中的空格(Whitespace in Expressions and Statements) == Pet Peeves Guido hates whitespace in the following places: |
== 空格 == (Whitespace in Expressions and Statements) |
| Line 182: | Line 179: |
| * Immediately inside parentheses, brackets or braces, as in: | |
| Line 189: | Line 185: |
| * Immediately before a comma, semicolon, or colon, as in: | |
| Line 197: | Line 192: |
| * Immediately before the open parenthesis that starts the argument list of a function call, as in {{{"spam (1)".}}} Always write this as {{{"spam(1)".}}} |
|
| Line 203: | Line 194: |
| * Immediately before the open parenthesis that starts an indexing or | |
| Line 209: | Line 199: |
* More than one space around an assignment (or other) operator to align it with another, as in: |
|
| Line 220: | Line 207: |
| Always write this as |
|
| Line 229: | Line 214: |
| (Don't bother to argue with him on any of the above -- Guido's grown accustomed to this style over 20 years.) |
|
| Line 234: | Line 217: |
| === 其它建议(Other Recommendations) === * Always surround these binary operators with a single space on either side: assignment (=), comparisons (==, <, >, !=, <>, <=, >=, in, not in, is, is not), Booleans (and, or, not). * 始终在这些二元运算符两边放置一个空格:赋值(=), 比较(==, <, >, !=, <>, <=, >=, in, not in, is, is not), 布尔运算 (and, or, not). * Use your better judgment for the insertion of spaces around arithmetic operators. Always be consistent about whitespace on either side of a binary operator. Some examples: * 按你的看法在算术运算符周围插入空格. 始终保持二元运算符两边空格的一致. 一些例子: |
=== 其它建议 === (Other Recommendations) * 始终在这些二元运算符两边放置一个空格:赋值(=), 比较(==, <, >, !=, <>, <=,>=, in, not in, is, is not), 布尔运算 (and, or, not). * 按你的看法在算术运算符周围插入空格. 始终保持二元运算符两边空格的一致. * 一些例子: |
| Line 258: | Line 234: |
| * Don't use spaces around the '=' sign when used to indicate a keyword argument or a default parameter value. For instance: |
|
| Line 267: | Line 240: |
| * Compound statements (multiple statements on the same line) are generally discouraged. |
|
| Line 281: | Line 251: |
== 注释(Comments) == Comments that contradict the code are worse than no comments. Always make a priority of keeping the comments up-to-date when the code changes! |
== 注释 == (Comments) |
| Line 290: | Line 257: |
| Comments should be complete sentences. If a comment is a phrase or sentence, its first word should be capitalized, unless it is an identifier that begins with a lower case letter (never alter the case of identifiers!). |
|
| Line 298: | Line 262: |
| If a comment is short, the period at the end is best omitted. Block comments generally consist of one or more paragraphs built out of complete sentences, and each sentence should end in a period. |
|
| Line 306: | Line 267: |
| You should use two spaces after a sentence-ending period, since it makes Emacs wrapping and filling work consistenty. |
|
| Line 312: | Line 272: |
| When writing English, Strunk and White apply. | |
| Line 316: | Line 275: |
| Python coders from non-English speaking countries: please write your comments in English, unless you are 120% sure that the code will never be read by people who don't speak your language. |
|
| Line 323: | Line 279: |
| === 注释块(Block Comments) === Block comments generally apply to some (or all) code that follows them, and are indented to the same level as that code. Each line of a block comment starts with a # and a single space (unless it is indented text inside the comment). Paragraphs inside a block comment are separated by a line containing a single #. Block comments are best surrounded by a blank line above and below them (or two lines above and a single line below for a block comment at the start of a a new section of function definitions). |
{{{我就是坚持全部使用中文来注释，真正要发布脚本工具时，再想E文的； 开发时每一瞬间都要用在思量中，坚决不用在E文语法，单词的回忆中！ }}}-- ZoomQUiet === 注释块 === (Block Comments) |
| Line 339: | Line 290: |
| === 行内注释(Inline Comments) === (inline?内联?翻成"行内"比较好吧) An inline comment is a comment on the same line as a statement. Inline comments should be used sparingly. Inline comments should be separated by at least two spaces from the statement. They should start with a # and a single space. |
=== 行内注释 === (Inline Comments) * (inline?内联?翻成"行内"比较好吧) |
| Line 351: | Line 299: |
| Inline comments are unnecessary and in fact distracting if they state the obvious. Don't do this: |
|
| Line 361: | Line 307: |
| But sometimes, this is useful: | |
| Line 371: | Line 316: |
| == 文档字符串(Documentation Strings) == | == 文档化 == (Documentation Strings) |
| Line 374: | Line 320: |
| (a.k.a. "docstrings") are immortalized in PEP 257 [3]. 应该一直遵守编写好的文档字符串(又名"docstrings")的约定(?实在不知道怎么译)PEP 257 [3]. |
(a.k.a. "docstrings") are immortalized in [wiki:epes/pep-0257.htm PEP 257]. 应该一直遵守编写好的文档字符串(又名"docstrings")的约定(?实在不知道怎么译) |
| Line 378: | Line 325: |
| 为了pydoc;epydoc,Doxygen等等文档化工具的使用,类似于MoinMoin 语法,约定一些字符, | 为配合 pydoc;epydoc,Doxygen等等文档化工具的使用,类似于MoinMoin 语法,约定一些字符, |
| Line 382: | Line 329: |
| * Write docstrings for all public modules, functions, classes, and methods. Docstrings are not necessary for non-public methods, but you should have a comment that describes what the method does. This comment should appear after the "def" line. * 为所有公共模块,函数,类和方法编写文档字符串. 文档字符串对非公开的方法不是必要的,但你应该有一个描述这个方法做什么的注释. 这个注释应该在"def"这行后. * PEP 257 describes good docstring conventions. Note that most importantly, the """ that ends a multiline docstring should be on a line by itself, e.g.: * PEP 257 描述了好的文档字符串的约定.一定注意,多行文档字符串结尾的""" |
* 为所有公共模块,函数,类和方法编写文档字符串.文档字符串对非公开的方法不是必要的,但你应该有一个描述这个方法做什么的注释.这个注释应该在"def"这行后. * [wiki:epes/pep-0257.htm PEP 257] 描述了好的文档字符串的约定.一定注意,多行文档字符串结尾的""" |
| Line 402: | Line 341: |
| * For one liner docstrings, it's okay to keep the closing """ on the same line. | |
| Line 406: | Line 344: |
| == 版本注记(Version Bookkeeping) == | {{{实际上Python 自个儿就使用文档化编码维护着所有内置对象的使用说明\ 不信的话常试: #python >>> import time >>> dir(time) ['__doc__', '__file__', '__name__', 'accept2dyear', 'altzone', 'asctime', 'clock', 'ctime', 'daylight', 'gmtime', 'localtime', 'mktime', 'sleep', 'strftime', 'strptime', 'struct_time', 'time', 'timezone', 'tzname', 'tzset'] >>> help(time.time) Help on built-in function time in module time: time(...) time() -> floating point number Return the current time in seconds since the Epoch. Fractions of a second may be present if the system clock provides them. }}} == 版本注记 == (Version Bookkeeping) |
| Line 409: | Line 364: |
| If you have to have RCS or CVS crud in your source file, do it as follows. | |
| Line 417: | Line 371: |
| These lines should be included after the module's docstring, before any other code, separated by a blank line above and below. |
|
| Line 433: | Line 386: |
| == 命名约定(Naming Conventions) == The naming conventions of Python's library are a bit of a mess, so we'll never get this completely consistent -- nevertheless, here are the currently recommended naming standards. New modules and packages (including 3rd party frameworks) should be written to these standards, but where an existing library has a different style, internal consistency is preferred. |
== 命名约定 == (Naming Conventions) |
| Line 447: | Line 395: |
| === 描述:命名风格(Descriptive: Naming Styles) === There are a lot of different naming styles. It helps to be able to recognize what naming style is being used, independently from what they are used for. |
=== 描述:命名风格 === (Descriptive: Naming Styles) |
| Line 455: | Line 401: |
| The following naming styles are commonly distinguished: |
|
| Line 459: | Line 403: |
| * b (single lowercase letter) |
|
| Line 462: | Line 404: |
* B (single uppercase letter) |
|
| Line 466: | Line 405: |
* lowercase |
|
| Line 470: | Line 406: |
* lower_case_with_underscores |
|
| Line 474: | Line 407: |
* UPPERCASE |
|
| Line 478: | Line 408: |
* UPPER_CASE_WITH_UNDERSCORES |
|
| Line 482: | Line 409: |
* CapitalizedWords (or CapWords, or CamelCase -- so named because of the bumpy look of its letters[4]). This is also sometimes known as StudlyCaps. |
|
| Line 490: | Line 412: |
* mixedCase (differs from CapitalizedWords by initial lowercase character!) |
|
| Line 495: | Line 413: |
* Capitalized_Words_With_Underscores (ugly!) |
|
| Line 500: | Line 415: |
| There's also the style of using a short unique prefix to group related names together. This is not used much in Python, but it is mentioned for completeness. For example, the os.stat() function returns a tuple whose items traditionally have names like st_mode, st_size, st_mtime and so on. The X11 library uses a leading X for all its public functions. (In Python, this style is generally deemed unnecessary because attribute and method names are prefixed with an object, and function names are prefixed with a module name.) |
|
| Line 516: | Line 423: |
| In addition, the following special forms using leading or trailing underscores are recognized (these can generally be combined with any case convention): |
|
| Line 522: | Line 427: |
| * _single_leading_underscore: weak "internal use" indicator (e.g. "from M import *" does not import objects whose name starts with an underscore). |
|
| Line 527: | Line 430: |
| (例如,"from M import *"不会导入以下划线开头的对象). * single_trailing_underscore_: used by convention to avoid conflicts with Python keyword, e.g. "Tkinter.Toplevel(master, class_='ClassName')". |
* (例如,"from M import *"不会导入以下划线开头的对象). |
| Line 534: | Line 432: |
| "Tkinter.Toplevel(master, class_='ClassName')". * {{{__double_leading_underscore}}}: class-private names as of Python 1.4. |
* "Tkinter.Toplevel(master, class_='ClassName')". |
| Line 540: | Line 435: |
| * {{{__double_leading_and_trailing_underscore__}}}: "magic" objects or attributes that live in user-controlled namespaces, e.g. {{{__init__}}}, {{{__import__}}} or {{{__file__}}}. Sometimes these are defined by the user to trigger certain magic behavior (e.g. operator overloading); sometimes these are inserted by the infrastructure for its own use or for debugging purposes. Since the infrastructure (loosely defined as the Python interpreter and the standard library) may decide to grow its list of magic attributes in future versions, user code should generally refrain from using this convention for its own use. User code that aspires to become part of the infrastructure could combine this with a short prefix inside the underscores, e.g. {{{__bobo_magic_attr__}}}. |
|
| Line 564: | Line 446: |
| === 说明:命名约定(Prescriptive: Naming Conventions) === ==== 应避免的名字(Names to Avoid) ==== Never use the characters `l' (lowercase letter el), `O' (uppercase letter oh), or `I' (uppercase letter eye) as single character variable names. In some fonts, these characters are indistinguisable from the numerals one and zero. When tempted to use `l' use `L' instead. |
=== 说明:命名约定 === (Prescriptive: Naming Conventions) ==== 应避免的名字 ==== (Names to Avoid) |
| Line 578: | Line 455: |
| ==== 模块名(Module Names) ==== Modules should have short, lowercase names, without underscores. |
==== 模块名 ==== (Module Names) |
| Line 584: | Line 460: |
| Since module names are mapped to file names, and some file systems are case insensitive and truncate long names, it is important that module names be chosen to be fairly short -- this won't be a problem on Unix, but it may be a problem when the code is transported to Mac or Windows. |
|
| Line 594: | Line 465: |
| When an extension module written in C or C++ has an accompanying Python module that provides a higher level (e.g. more object oriented) interface, the C/C++ module has a leading underscore (e.g. _socket). |
|
| Line 602: | Line 469: |
| Python packages should have short, all-lowercase names, without underscores. |
|
| Line 607: | Line 472: |
| ==== 类名(Class Names) ==== Almost without exception, class names use the CapWords convention. Classes for internal use have a leading underscore in addition. |
==== 类名 ==== (Class Names) |
| Line 614: | Line 477: |
| ==== 异常名(Exception Names) ==== If a module defines a single exception raised for all sorts of conditions, it is generally called "error" or "Error". It seems that built-in (extension) modules use "error" (e.g. os.error), while Python modules generally use "Error" (e.g. xdrlib.Error). The trend seems to be toward CapWords exception names. |
==== 异常名 ==== (Exception Names) |
| Line 627: | Line 485: |
| ==== 全局变量名(Global Variable Names) ==== (Let's hope that these variables are meant for use inside one module only.) The conventions are about the same as those for functions. Modules that are designed for use via "from M import *" should prefix their globals (and internal functions and classes) with an underscore to prevent exporting them. |
==== 全局变量名 ==== (Global Variable Names) |
| Line 639: | Line 492: |
| ==== 函数名(Function Names) ==== Function names should be lowercase, possibly with words separated by underscores to improve readability. mixedCase is allowed only in contexts where that's already the prevailing style (e.g. threading.py), to retain backwards compatibility. |
==== 函数名 ==== (Function Names) |
| Line 650: | Line 499: |
| ==== 方法名和实例变量(Method Names and Instance Variables) ==== The story is largely the same as with functions: in general, use lowercase with words separated by underscores as necessary to improve readability. |
==== 方法名和实例变量 ==== (Method Names and Instance Variables) |
| Line 658: | Line 505: |
| Use one leading underscore only for internal methods and instance variables which are not intended to be part of the class's public interface. Python does not enforce this; it is up to programmers to respect the convention. |
|
| Line 666: | Line 510: |
| Use two leading underscores to denote class-private names. Python "mangles" these names with the class name: if class Foo has an attribute named {{{__a}}}, it cannot be accessed by {{{Foo.__a}}}. (An insistent user could still gain access by calling {{{Foo._Foo__a}}}.) Generally, double leading underscores should be used only to avoid name conflicts with attributes in classes designed to be subclassed. |
|
| Line 678: | Line 517: |
| ==== 继承的设计(Designing for inheritance) ==== Always decide whether a class's methods and instance variables should be public or non-public. In general, never make data variables public unless you're implementing essentially a record. It's almost always preferrable to give a functional interface to your class instead (and some Python 2.2 developments will make this much nicer). |
==== 继承的设计 ==== (Designing for inheritance) |
| Line 692: | Line 525: |
| Also decide whether your attributes should be private or not. The difference between private and non-public is that the former will never be useful for a derived class, while the latter might be. Yes, you should design your classes with inheritence in mind! |
|
| Line 702: | Line 531: |
| Private attributes should have two leading underscores, no trailing underscores. |
|
| Line 707: | Line 534: |
| Non-public attributes should have a single leading underscore, no trailing underscores. |
|
| Line 712: | Line 537: |
| Public attributes should have no leading or trailing underscores, unless they conflict with reserved words, in which case, a single trailing underscore is preferrable to a leading one, or a corrupted spelling, e.g. class_ rather than klass. (This last point is a bit controversial; if you prefer klass over class_ then just be consistent. :). |
|
| Line 724: | Line 544: |
| == 设计建议(Programming Recommendations) == * Comparisons to singletons like None should always be done with 'is' or 'is not'. Also, beware of writing "if x" when you really mean "if x is not None" -- e.g. when testing whether a variable or argument that defaults to None was set to some other value. The other value might be a value that's false in a Boolean context! |
== 设计建议 == (Programming Recommendations) |
| Line 738: | Line 554: |
| * Class-based exceptions are always preferred over string-based exceptions. Modules or packages should define their own domain-specific base exception class, which should be subclassed from the built-in Exception class. Always include a class docstring. E.g.: |
|
| Line 754: | Line 566: |
| * Use string methods instead of the string module unless backward-compatibility with versions earlier than Python 2.0 is important. String methods are always much faster and share the same API with unicode strings. |
|
| Line 762: | Line 571: |
| * Avoid slicing strings when checking for prefixes or suffixes. Use startswith() and endswith() instead, since they are cleaner and less error prone. For example: |
|
| Line 767: | Line 574: |
| Line 774: | Line 582: |
| The exception is if your code must work with Python 1.5.2 (but let's hope not!). |
|
| Line 778: | Line 584: |
* Object type comparisons should always use isinstance() instead of comparing types directly. E.g. |
|
| Line 788: | Line 590: |
| When checking if an object is a string, keep in mind that it might be a unicode string too! In Python 2.3, str and unicode have a common base class, basestring, so you can do: |
|
| Line 799: | Line 597: |
| In Python 2.2, the types module has the StringTypes type defined for that purpose, e.g.: |
|
| Line 809: | Line 604: |
| In Python 2.0 and 2.1, you should do: | |
| Line 819: | Line 613: |
| * For sequences, (strings, lists, tuples), use the fact that empty sequences are false, so "if not seq" or "if seq" is preferable to "if len(seq)" or "if not len(seq)". |
|
| Line 827: | Line 618: |
| * Don't write string literals that rely on significant trailing whitespace. Such trailing whitespace is visually indistinguishable and some editors (or more recently,reindent.py) will trim them. |
|
| Line 835: | Line 624: |
| * Don't compare boolean values to True or False using == (bool types are new in Python 2.3): |
译稿 Python开发编码规范
Python开发编码规范
--- hoxide 初译 dreamingk 校对发布 040724 --- xyb 重新排版 040915 --- ZoomQuiet MoinMoin 美化 050610
用Python进行开发时的编码风格约定 原文:[wiki:epes/pep-0008.html PEP 008]《Style Guide for Python Code》
介绍
- 这篇文档所给出的编码约定适用于在主要的Python发布版本中组成标准库的Python 代码.请查阅相关的关于在Python的C实现中C代码风格指南的描述. 这篇文档改编自Guido最初的《Python风格指南》一文. 并从《Barry's style guide》中添加了部分内容. 在有冲突的地方，Guide的风格规则应该是符合本PEP的意图 (译注：就是当有冲突时，应以Guido风格为准) 这篇PEP也许仍然尚未完成(实际上，它可能永远不会结束).
一致性的建议
愚蠢得使用一致性是无知的妖怪(A Foolish Consistency is the Hobgoblin of Little Minds) {{{呆板的坚持一致性是傻的没边了! -- Zoomq}}}
- 在这篇风格指导中的一致性是重要的. 在一个项目内的一致性更重要. 在一个模块或函数内的一致性最重要. 但最重要的是:知道何时会不一致 -- 有时只是没有实施风格指导.当出现疑惑时,
- 运用你的最佳判断.看看别的例子,然后决定怎样看起来更好.并且要不耻下问!
- 打破一条既定规则的两个好理由:
- 当应用这个规则是将导致代码可读性下降,即便对某人来说,他已经习惯于按这条规则来阅读代码了.
- 为了和周围的代码保持一致而打破规则(也许是历史原因)
- -- 虽然这也是个清除其它混乱的好机会(真正的XP风格).
代码的布局
(Code lay-out)
缩进
(Indentation)
- 使用Emacs的Python-mode的默认值:4个空格一个缩进层次. 对于确实古老的代码,你不希望产生混乱,可以继续使用8空格的制表符(8-space tabs). Emacs Python-mode自动发现文件中主要的缩进层次,依此设定缩进参数.
制表符还是空格?
(Tabs or Spaces)
- 永远不要混用制表符和空格. 最流行的Python缩进方式是仅使用空格, 其次是仅使用制表符.混合着制表符和空格缩进的代码将被转换成仅使用空格. (在Emacs中,选中整个缓冲区,按ESC-x去除制表符(untabify).) 调用python命令行解释器时使用-t选项,可对代码中不合法得混合制表符和空格发出警告(warnings). 使用-tt时警告(warnings)将变成错误(errors).这些选项是被高度推荐的. 对于新的项目,强烈推荐仅使用空格(spaces-only)而不是制表符. 许多编辑器拥有使之易于实现的功能.(在Emacs中,确认indent-tabs-mode是nil).
行的最大长度
(Maximum Line Length)
- 周围仍然有许多设备被限制在每行80字符;而且,窗口限制在80个字符 使将多个窗口并排放置成为可能.在这些设备上使用默认的折叠(wrapping)方式看起来有点丑陋. 因此,请将所有行限制在最大79字符(Emacs准确得将行限制为长80字符), 对顺序排放的大块文本(文档字符串或注释),推荐将长度限制在72字符. 折叠长行的首选方法是使用Pyhon支持的圆括号,方括号(brackets)和花括号(braces)内的行延续. 如果需要,你可以在表达式周围增加一对额外的圆括号, 但是有时使用反斜杠看起来更好.确认恰当得缩进了延续的行. Emacs的Python-mode正确得完成了这些.一些例子:
1 class Rectangle(Blob):
2
3 def __init__(self, width, height,
4 color='black', emphasis=None, highlight=0):
5 if width == 0 and height == 0 and \
6 color == 'red' and emphasis == 'strong' or \
7 highlight > 100:
8 raise ValueError, "sorry, you lose"
9 if width == 0 and height == 0 and (color == 'red' or
10 emphasis is None):
11 raise ValueError, "I don't think so"
12 Blob.__init__(self, width, height,
13 color, emphasis, highlight)
空行
(Blank Lines)
- 用两行空行分割顶层函数和类的定义,类内方法的定义用单个空行分割. 额外的空行可被用于(保守的(sparingly))分割相关函数组成的群(groups of related functions). 在一组相关的单句中间可以省略空行.(例如.一组哑元(a set of dummy implementations)). 当空行用于分割方法(method)的定义时,在'class'行和第一个方法定义之间也要有一个空行. 在函数中使用空行时,请谨慎的用于表示一个逻辑段落(indicate logical sections). Python接受contol-L(即^L)换页符作为空格;Emacs(和一些打印工具) 视这个字符为页面分割符,因此在你的文件中,可以用他们来为相关片段(sections)分页.
编码
(Encodings)[wiki:epes/pep-0263.html (PEP 263)]
- Python核心发布中的代码必须始终使用ASCII或Latin-1编码(又名 ISO-8859-1). 使用ASCII的文件不必有译码cookie(coding cookie). Latin-1仅当注释或文档字符串涉及作者名字需要Latin-1时才被使用; 另外使用\x转义字符是在字符串中包含非ASCII(non-ASCII)数据的首选方法. 作为PEP 263实现代码的测试套件的部分文件是个例外.
{{{Python 2.4 以后内核支持 Unicode 了！ 不论什么情况使用 UTF-8 吧！这是王道！ }}}--ZoomQuiet
导入
(Imports)
- 通常应该在单独的行中导入(Imports),例如:
No: import sys, os
Yes: import sys
import os- 但是这样也是可以的:
from types import StringType, ListType
- Imports 通常被放置在文件的顶部,仅在模块注释和文档字符串之后,在模块的全局变量和常量之前.Imports应该有顺序地成组安放.
- 标准库的导入(Imports )
- 相关的主包(major package)的导入(即,所有的email包在随后导入)
- 特定应用的导入(imports)
- 你应该在每组导入之间放置一个空行.
- 对于内部包的导入是不推荐使用相对导入的.对所有导入都要使用包的绝对路径.
- 从一个包含类的模块中导入类时,通常可以写成这样:
from MyClass import MyClass
from foo.bar.YourClass import YourClass- 如果这样写导致了本地名字冲突,那么就这样写
import MyClass
import foo.bar.YourClass即使用"MyClass.MyClass"和"foo.bar.YourClass.YourClass"
空格
(Whitespace in Expressions and Statements)
- Guido不喜欢在以下地方出现空格:
"spam( ham[ 1 ], { eggs: 2 } )". Always write this as "spam(ham[1], {eggs: 2})".
紧挨着圆括号,方括号和花括号的,如:"spam( ham[ 1 ], { eggs: 2 } )".
要始终将它写成"spam(ham[1], {eggs: 2})".
"if x == 4 : print x , y ; x , y = y , x". Always write this as "if x == 4: print x, y; x, y = y, x".
- 紧贴在逗号,分号或冒号前的,如:
"if x == 4 : print x , y ; x , y = y , x". 要始终将它写成 "if x == 4: print x, y; x, y = y, x".
紧贴着函数调用的参数列表前开式括号(open parenthesis )的,如"spam (1)".要始终将它写成"spam(1)".
slicing, as in: "dict ['key'] = list [index]". Always write this as "dict['key'] = list[index]".
- 紧贴在索引或切片(slicing?下标?)开始的开式括号前的,如:
"dict ['key'] = list [index]".要始终将它写成"dict['key'] = list[index]".
- 在赋值(或其它)运算符周围的用于和其它并排的一个以上的空格,如:
- 要始终将它写成
- (不要对以上任意一条和他争论 --- Guido 养成这样的风格超过20年了.)
其它建议
(Other Recommendations)
始终在这些二元运算符两边放置一个空格:赋值(=), 比较(==, <, >, !=, <>, <=,>=, in, not in, is, is not), 布尔运算 (and, or, not).
* 按你的看法在算术运算符周围插入空格. 始终保持二元运算符两边空格的一致.
- 一些例子:
- 不要在用于指定关键字参数或默认参数值的'='号周围使用空格,例如:
- 不要将多条语句写在同一行上.
No: if foo == 'blah': do_blah_thing()
Yes: if foo == 'blah':
do_blah_thing()
No: do_one(); do_two(); do_three()
Yes: do_one()
do_two()
do_three()
注释
(Comments)
- 同代码不一致的注释比没注释更差.当代码修改时,始终优先更新注释! 注释应该是完整的句子. 如果注释是一个短语或句子,首字母应该大写, 除非他是一个以小写字母开头的标识符(永远不要修改标识符的大小写). 如果注释很短,最好省略末尾的句号(period?结尾句末的停顿?也可以是逗号吧,) 注释块通常由一个或多个由完整句子构成的段落组成,每个句子应该以句号结尾. 你应该在句末,句号后使用两个空格,以便使Emacs的断行和填充工作协调一致 (译按:应该说是使这两种功能正常工作,". "给出了文档结构的提示). 用英语书写时,断词和空格是可用的. 非英语国家的Python程序员:请用英语书写你的注释,除非你120%的确信 这些代码不会被不懂你的语言的人阅读.
{{{我就是坚持全部使用中文来注释，真正要发布脚本工具时，再想E文的； 开发时每一瞬间都要用在思量中，坚决不用在E文语法，单词的回忆中！ }}}-- ZoomQUiet
注释块
(Block Comments)
- 注释块通常应用于跟随着一些(或者全部)代码并和这些代码有着相同的缩进层次. 注释块中每行以'#'和一个空格开始(除非他是注释内的缩进文本). 注释块内的段落以仅含单个'#'的行分割. 注释块上下方最好有一空行包围(或上方两行下方一行,对一个新函数定义段的注释).
行内注释
(Inline Comments)
- (inline?内联?翻成"行内"比较好吧)
- 一个行内注释是和语句在同一行的注释.行内注释应该谨慎适用. 行内注释应该至少用两个空格和语句分开. 它们应该以'#'和单个空格开始.
x = x+1 # Increment x
- 如果语意是很明了的,那么行内注释是不必要的,事实上是应该被去掉的. 不要这样写:
x = x+1 # Increment x
x = x+1 # Compensate for border
- 但是有时,这样是有益的:
x = x+1 # Compensate for border
文档化
(Documentation Strings)
- Conventions for writing good documentation strings (a.k.a. "docstrings") are immortalized in [wiki:epes/pep-0257.htm PEP 257]. 应该一直遵守编写好的文档字符串(又名"docstrings")的约定(?实在不知道怎么译)
{{{Documentation Strings-- 文档化字符 ; 为配合 pydoc;epydoc,Doxygen等等文档化工具的使用,类似于MoinMoin 语法,约定一些字符, 以便自动提取转化为有意义的文档章节等等文章元素! -- Zoomq}}}
- 为所有公共模块,函数,类和方法编写文档字符串.文档字符串对非公开的方法不是必要的,但你应该有一个描述这个方法做什么的注释.这个注释应该在"def"这行后.
- [wiki:epes/pep-0257.htm PEP 257] 描述了好的文档字符串的约定.一定注意,多行文档字符串结尾的""" 应该单独成行,例如:
"""Return a foobang
Optional plotz says to frobnicate the bizbaz first.
"""- 对单行的文档字符串,结尾的"""在同一行也可以.
{{{实际上Python 自个儿就使用文档化编码维护着所有内置对象的使用说明\ 不信的话常试:
- #python
>>> import time >>> dir(time) ['doc', 'file', 'name', 'accept2dyear', 'altzone', 'asctime', 'clock', 'ctime', 'daylight', 'gmtime', 'localtime', 'mktime', 'sleep', 'strftime', 'strptime', 'struct_time', 'time', 'timezone', 'tzname', 'tzset'] >>> help(time.time) Help on built-in function time in module time:
time(...)
time() -> floating point number Return the current time in seconds since the Epoch. Fractions of a second may be present if the system clock provides them.
}}}
版本注记
(Version Bookkeeping) (我觉得叫"注记"更好)
- 如果你要将RCS或CVS的杂项(crud)包含在你的源文件中,按如下做.
- 这个行应该包含在模块的文档字符串之后,所有代码之前,上下用一个空行分割.