原文地址:https://gist.github.com/sloria/7001839
感觉合理的话,就遵循PEP 8。
一般命名准则
尽量不要使用只有一个字母的变量名(例如,l,I,O等)。
例外:在很简短的代码块中,如果变量名的意思可以从上下文明显地看出来,即可。
for e in elements: e.mutate()
避免重复变量名。
import audio core = audio.Core() controller = audio.Controller()
import audio core = audio.AudioCore() controller = audio.AudioController()
“反向标记”更好。
elements = ... elements_active = ... elements_defunct = ...
elements = ... active_elements = ... defunct_elements ...
避免使用getter和setter方法。
person.age = 42
person.set_age(42)
用4个空格符——永远别用Tab制表符。就说这么多。
引用整个模块,而不是模块中的单个标识符。举个例子,假设一个cantee模块下面,有一个sessions.py文件,
import canteen import canteen.sessions from canteen import sessions
from canteen import get_user # Symbol from canteen/__init__.py from canteen.sessions import get_session # Symbol from canteen/sessions.py
例外 :如果第三方代码的文档中明确说明要单个引用,即可。
理由 :避免循环引用。看 这里 。
把代码引用部分放在文件的顶部,按下面的顺序分成三个部分,每个部分之间空一行。 1. 系统引用 2. 第三方引用 3. 本地引用
理由 :明确显示每个模块的引用来源。
遵循 PEP 257 提出的文档字符串准则。reStructuredText (reST) 和Sphinx有助于确保文档符合标准。
对于功能明显的函数,撰写一行文档字符串。
"""返回``foo``的路径名."""
多行文档字符串应包括:
返回数据类型和语义信息,除非返回 None
"""训练一个用来区分Foo和Bar的模型。
用法::
>>> import klassify >>> data = [("green", "foo"), ("orange", "bar")] >>> classifier = klassify.train(data)
:param train_data: (color, label)
形式的一个元祖列表。
:rtype: A :class: Classifier <Classifier>
"""
注意
使用主动词(“返回”),而不是描述性的单词(“返回值”)。 在类的文档字符串中为 __init__
方法撰写文档。
class Person(object): """A simple representation of a human being. :param name: A string, the person's name. :param age: An int, the person's age. """ def __init__(self, name, age): self.name = name self.age = age
关于注释
尽量少用。与其写很多注释,不如提高代码可读性。通常情况下,短小的方法比注释更有效。
# If the sign is a stop sign if sign.color == 'red' and sign.sides == 8: stop()
def is_stop_sign(sign): return sign.color == 'red' and sign.sides == 8 if is_stop_sign(sign): stop()
但是的确要写注释时,请牢记:“遵循斯托克与怀特所写的《风格的要素》。” —— PEP 8
不要过分在意。80到100个字符都是没问题的。
使用括号延续当前行。
wiki = ( "The Colt Python is a .357 Magnum caliber revolver formerly manufactured " "by Colt's Manufacturing Company of Hartford, Connecticut. It is sometimes " 'referred to as a "Combat Magnum". It was first introduced in 1955, the ' "same year as Smith & Wesson's M29 .44 Magnum." )
尽量争取测试全部代码,但也不必执着于覆盖率。
assert False, "TODO: finish me"
。 通常,每一个类或模型都应该有一个测试用例类。
import unittest import factories
class PersonTest(unittest.TestCase): def setUp(self): self.person = factories.PersonFactory()
def test_has_age_in_dog_years(self): self.assertEqual(self.person.dog_years, self.person.age / 7)
功能测试是更高层次的测试,更接近最终用户如何与应用交互这一层面。通常用在网络应用与图形应用测试。
在编写代码之前,通过注释说明具体场景信息。
import unittest
class TestAUser(unittest.TestCase):
def test_can_write_a_blog_post(self): # Goes to the her dashboard ... # Clicks "New Post" ... # Fills out the post form ... # Clicks "Submit" ... # Can see the new post ...
请注意,测试用例的类名称和测试方法的名称放在一起,就像是“测试一名用户能否发布博文”。