Python[三]:Coding Style
2010-07-07 21:47
357 查看
规范
Documentation Strings
Here are some conventions about the content and formatting of documentation strings.The first line should always be a short, concise summary of the object’s purpose. For brevity, it should not explicitly state the object’s name or type, since these are available by other means (except if the name happens to be a verb describing a function’s operation). This line should begin with a capital letter and end with a period.
If there are more lines in the documentation string, the second line should be blank, visually separating the summary from the rest of the description. The following lines should be one or more paragraphs describing the object’s calling conventions, its side effects, etc.
The Python parser does not strip indentation from multi-line string literals in Python, so tools that process documentation have to strip indentation if desired. This is done using the following convention. The first non-blank line after the first line of the string determines the amount of indentation for the entire documentation string. (We can’t use the first line since it is generally adjacent to the string’s opening quotes so its indentation is not apparent in the string literal.) Whitespace “equivalent” to this indentation is then stripped from the start of all lines of the string. Lines that are indented less should not occur, but if they occur all their leading whitespace should be stripped. Equivalence of whitespace should be tested after expansion of tabs (to 8 spaces, normally).
Here is an example of a multi-line docstring:
>>> def my_function(): ... """Do nothing, but document it. ... ... No, really, it doesn't do anything. ... """ ... pass... >>> print(my_function.__doc__) Do nothing, but document it. No, really, it doesn't do anything.
Intermezzo: Coding Style
Now that you are about to write longer, more complex pieces of Python, it is a good time to talk about coding style. Most languages can be written (or more concise, formatted) in different styles; some are more readable than others. Making it easy for others to read your code is always a good idea, and adopting a nice coding style helps tremendously for that.For Python, PEP 8 has emerged as the style guide that most projects adhere to; it promotes a very readable and eye-pleasing coding style. Every Python developer should read it at some point; here are the most important points extracted for you:
Use 4-space indentation, and no tabs.
4 spaces are a good compromise between small indentation (allows greater nesting depth) and large indentation (easier to read). Tabs introduce confusion, and are best left out.
Wrap lines so that they don’t exceed 79 characters.
This helps users with small displays and makes it possible to have several code files side-by-side on larger displays.
Use blank lines to separate functions and classes, and larger blocks of code inside functions.
When possible, put comments on a line of their own.
Use docstrings.
Use spaces around operators and after commas, but not directly inside bracketing constructs: a = f(1, 2)+ g(3, 4).
Name your classes and functions consistently; the convention is to use CamelCase for classes andlower_case_with_underscores for functions and methods. Always use self as the name for the first method argument (see A First Look at Classes for more on classes and methods).
Don’t use fancy encodings if your code is meant to be used in international environments. Plain ASCII works best in any case.
相关文章推荐
- python coding style guide 的快速落地实践
- python coding style guide 的高速落地实践
- Coding Style for python
- python之coding style
- android coding style
- 关于Python脚本开头两行的:#!/usr/bin/python和# -*- coding: utf-8 -*-的作用 – 指定文件编码类型
- Recommended C Style and Coding Standards中文翻译版第1/3页
- Kernel Coding style
- [C学习笔记].CodingStyle[en]
- Python的编码注释# -*- coding:utf-8 -*-
- C# Coding Style Guide
- how to call c++ function in python coding in linux?
- 谈谈Linux内核驱动的coding style
- python开头的coding设置
- C# Coding Style Guide
- Linux kernel coding style
- [文档].Actel – Actel HDL Coding Style Guide
- 【原创】Verilog TestBench Coding Style【Verilog】
- python遇到SyntaxError: Non-ASCII character '\xc3' in file pic2char.py on line 4, but coding declared;
- Google C++ Coding Style:引用参数