Python代碼風格建議（轉）

python 以其結構嚴格著稱，同時也以其命名規範散漫出名，算亂無規矩的命名尤爲給開發人員帶來理解上的誤區。

尤爲像python、ruby動態語言，因爲在運行期隨時可能出現方法或者屬性的增減，規則的命名尤爲重要。

 

ruby語言自己定義的語法規則較爲隨意，但卻不乏一一對應的隱含規則，令人一目瞭然。其命名規則甚至滲透進了語言自己的規範當中

在命名規則這一點上python顯得沒規沒距。須要逐步養成一個好的編碼命名規範。

 

本文從各大站點文章中搜集了一些代碼風格，命名規範。便於學習參考。

 

 

代碼風格：

 

1. 使用空格來表示縮進，而不要使用製表符tab，請勿將二者混用
2. 函數間換行至少一行
3. 類之間換行至少兩行
4. dict、list、tuple、參數列表時，應該在逗號，前添加一個空格
5. dict中key以後的冒號：應在value與冒號：之間添加空格，而不是：與key以前間
6. 較長代碼（大於79chars）使用反斜槓\換行。換行後新行的起始處應該與前一個分隔符對齊（是參數換行則與左括號（對齊
7. import位於module comments 與 docstring 以後，常量聲明以前
8. 3.0一下版本的代碼文件建議以latin字符編碼。3.0以上則推薦utf-8
9. 代碼中有操做符運算，請注意優先級，優先的操做緊縮，或者加括號
10. 等號左右兩邊請勿加空格
11. 儘可能不要將多行代碼放在同一行
12. 少使用inline comments（行後註釋）
13. block comments （用#開頭的多行函數註釋），保持與目標函數 相同的縮進
14. docstring ，開頭一行寫上返回值，接下來一行寫函數功能描述，後可按照格式>>>func(arg1, arg2, arg3) /r 返回值。以便於測試
15. 另外，若要使用subversion，cvs等源代碼管理工具。能夠在函數的docstring 以後，code以前 寫上
    1.  __version__ = "Revision:16dd63848921"

 

命名規則：

1. 儘可能少用 'l' (lowercase letter el), 'O' (uppercase letter oh), or 'I' (uppercase letter eye) 單字母做爲變量的命名.-------no l,I,O
2. 包和模塊應該用短且全小寫字母（Modules should have short, all-lowercase names.）:thismoduleisnew
3. class name 則建議用CapWords（首字母大寫）的形式命名:NewClassName
4. Exception類則用以Error結尾的字符串命名爲宜: NewError
5. 全局變量儘可能只是設計用於模塊內使用，而且能夠用import *時，包內的__all__機制來除去全局變量
6. 函數名（function name） 儘可能都用小寫且單詞間以_(下劃線)鏈接，另外，大小混合的mixedCase植被容許用於傳統類中。function_name(arg1...)
7. 函數和方法參數（function and method arguments）,self做爲實例方法的第一個參數，cls做爲類方法的第一個參數，假若參數名與關鍵字相同，爲了避諱，則應該加個下劃線
8. 方法名&類實例的屬性（method name & instance variable）方法名規則與函數名相同，類實例私有屬性 和 類實例的私有方法以單個下劃線開頭_private_fucntion_name(self)
9. 常量;全大寫，單詞間以_下弧線間隔:THIS_IS_CONSTANT_VAR
10. 面向對象設計建議：
    1. 若對類實例中的屬性是設置成public的好仍是private好，能夠考慮先設置成private，其修改爲本更低。
    2. private不能被第三方使用，由於隨時有可能被刪除、廢棄
    3. public屬性不能用下劃線開頭
    4. 避免屬性使用大運算量操做
    5. 假若不想被子類繼承的屬性，應該用雙下劃線開頭，且最後沒有下劃線。這樣會啓動python的命名識別矯正處理算法，保證不被繼承

 

 

1. joined_lower 能夠是函數名 方法名 屬性名
2. ALL_CAPS 是常量
3. StudlyCaps是類名
4. camelCase 只有在預先訂製好的命名規範中使用
5. 屬性 interface，_internal, __private
6. 儘可能避免__private形式，下面兩個鏈接解釋了爲何python中沒有private聲明

 

 

最後沒時間翻譯了，有時間再來。

 

Reference：  http://www.python.org/dev/peps/pep-0008/#naming-conventions

 

 

 

Programming Recommendations

• Code should be written in a way that does not disadvantage other implementations of Python (PyPy, Jython, IronPython, Cython, Psyco, and such).

  For example, do not rely on CPython's efficient implementation of in-place string concatenation for statements in the form a += b or a = a + b. Those statements run more slowly in Jython. In performance sensitive parts of the library, the ''.join() form should be used instead. This will ensure that concatenation occurs in linear time across various implementations.

• Comparisons to singletons like None should always be done with is or is not, never the equality operators.

  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 have a type (such as a container) that could be false in a boolean context!

• When implementing ordering operations with rich comparisons, it is best to implement all six operations (__eq__, __ne__, __lt__, __le__, __gt__, __ge__) rather than relying on other code to only exercise a particular comparison.

  To minimize the effort involved, the functools.total_ordering() decorator provides a tool to generate missing comparison methods.

  PEP 207 indicates that reflexivity rules are assumed by Python. Thus, the interpreter may swap y > x with x < y, y >= x with x <= y, and may swap the arguments of x == y and x != y. The sort() and min() operations are guaranteed to use the < operator and the max() function uses the > operator. However, it is best to implement all six operations so that confusion doesn't arise in other contexts.

• Use class-based exceptions.

  String exceptions in new code are forbidden, because this language feature is being removed in Python 2.6.

  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.:

  class MessageError(Exception):
      """Base class for errors in the email package."""
  

  Class naming conventions apply here, although you should add the suffix "Error" to your exception classes, if the exception is an error. Non-error exceptions need no special suffix.

• When raising an exception, use raise ValueError('message') instead of the older form raise ValueError, 'message'.

  The paren-using form is preferred because when the exception arguments are long or include string formatting, you don't need to use line continuation characters thanks to the containing parentheses. The older form will be removed in Python 3.

• When catching exceptions, mention specific exceptions whenever possible instead of using a bare except: clause.

  For example, use:

  try:
      import platform_specific_module
  except ImportError:
      platform_specific_module = None
  

  A bare except: clause will catch SystemExit and KeyboardInterrupt exceptions, making it harder to interrupt a program with Control-C, and can disguise other problems. If you want to catch all exceptions that signal program errors, use except Exception: (bare except is equivalent to except BaseException:).

  A good rule of thumb is to limit use of bare 'except' clauses to two cases:

  1. If the exception handler will be printing out or logging the traceback; at least the user will be aware that an error has occurred.
  2. If the code needs to do some cleanup work, but then lets the exception propagate upwards with raise. try...finally can be a better way to handle this case.

• Additionally, for all try/except clauses, limit the try clause to the absolute minimum amount of code necessary. Again, this avoids masking bugs.

  Yes:

  try:
      value = collection[key]
  except KeyError:
      return key_not_found(key)
  else:
      return handle_value(value)
  

  No:

  try:
      # Too broad!
      return handle_value(collection[key])
  except KeyError:
      # Will also catch KeyError raised by handle_value()
      return key_not_found(key)
  

• Context managers should be invoked through separate functions or methods whenever they do something other than acquire and release resources. For example:

  Yes:

  with conn.begin_transaction():
      do_stuff_in_transaction(conn)
  

  No:

  with conn:
      do_stuff_in_transaction(conn)
  

  The latter example doesn't provide any information to indicate that the __enter__ and __exit__ methods are doing something other than closing the connection after a transaction. Being explicit is important in this case.

• Use string methods instead of the string module.

  String methods are always much faster and share the same API with unicode strings. Override this rule if backward compatibility with Pythons older than 2.0 is required.

• Use ''.startswith() and ''.endswith() instead of string slicing to check for prefixes or suffixes.

  startswith() and endswith() are cleaner and less error prone. For example:

  Yes: if foo.startswith('bar'):
  No:  if foo[:3] == 'bar':
  

  The exception is if your code must work with Python 1.5.2 (but let's hope not!).

• Object type comparisons should always use isinstance() instead of comparing types directly.

  Yes: if isinstance(obj, int):
  
  No:  if type(obj) is type(1):
  

  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:

  if isinstance(obj, basestring):
  

• For sequences, (strings, lists, tuples), use the fact that empty sequences are false.

  Yes: if not seq:
       if seq:
  
  No: if len(seq)
      if not len(seq)
  

• 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.

• Don't compare boolean values to True or False using ==.

  Yes:   if greeting:
  No:    if greeting == True:
  Worse: if greeting is True:
  

• The Python standard library will not use function annotations as that would result in a premature commitment to a particular annotation style. Instead, the annotations are left for users to discover and experiment with useful annotation styles.

  Early core developer attempts to use function annotations revealed inconsistent, ad-hoc annotation styles. For example:

  • [str] was ambiguous as to whether it represented a list of strings or a value that could be either str or None.
  • The notation open(file:(str,bytes)) was used for a value that could be either bytes or str rather than a 2-tuple containing a str value followed by abytes value.
  • The annotation seek(whence:int) exhibited an mix of over-specification and under-specification: int is too restrictive (anything with __index__ would be allowed) and it is not restrictive enough (only the values 0, 1, and 2 are allowed). Likewise, the annotation write(b: bytes) was also too restrictive (anything supporting the buffer protocol would be allowed).
  • Annotations such as read1(n: int=None) were self-contradictory since None is not an int. Annotations such as source_path(self, fullname:str) -> objectwere confusing about what the return type should be.
  • In addition to the above, annotations were inconsistent in the use of concrete types versus abstract types: int versus Integral and set/frozenset versus MutableSet/Set.
  • Some annotations in the abstract base classes were incorrect specifications. For example, set-to-set operations require other to be another instance of Set rather than just an Iterable.
  • A further issue was that annotations become part of the specification but weren't being tested.
  • In most cases, the docstrings already included the type specifications and did so with greater clarity than the function annotations. In the remaining cases, the docstrings were improved once the annotations were removed.
  • The observed function annotations were too ad-hoc and inconsistent to work with a coherent system of automatic type checking or argument validation. Leaving these annotations in the code would have made it more difficult to make changes later so that automated utilities could be supported.