[俄勒冈大学]养成Python写作习惯

NOTE:本文翻译自俄勒冈大学计算机科学课程讲义，翻译者赤石俊哉，本文不允许转载。翻译时完全不遵照原文……其实只是挑重点翻译了一下做了个总结。
P.S. 我不是俄勒冈大学的……

谁在乎写作风格呢？

可能写作风格听起来好像没什么大不了的嘛，口胡，我们说的“写作风格”啊，既然是“风格”的话，就是一堆为了使我们的程序容易被人家阅读和理解以及修改的一些笔记。
首先呢，一个程序是需要不断地修改的，你可能用一个程序解决了一个问题，下次遇到相似的问题的时候，重复造轮子是不必要的，你完全可以从上次的程序上修改一下达到目的。再造一个轮子你又是何苦呢。而事实上，你写的程序可能要被别人拿去重用，或者说你需要重用别人写的程序，然而阅读别人的代码并且决定需要修改什么是很费时间的。
那么知道了写作风格的重要性，我们再来说说当我们写程序的时候都需要注意哪些写作风格呢？

头部注释

记住，在每一个程序的开头，你都需要写一个基本的头部注释，可以像这样:

'''Make me coffee.  Assignment 12, CIS 210Authors:  Alfred J. Neumann and Maria K. NortonCredits: Consulted with Electra Onn regarding bluetooth protocols (but wrote access protocols independently). Wifi protocol code based on Smith & Jones, "Over the air protocol engineering", pp 23-25.Uses public wifi networks to locate and commandeer coffee machines. Optional features implemented: Decaf mode also works over bluetooth networks.'''

这些表示表示主题和作者（前两行），以及最后两行简短的说明应该每次都写出来，中间的鸣谢，则可以在你使用了参考代码（不管是网上的还是书上的）的时候写出来。当然你要是有询问过其他同学或者是老师以及其他教员等，也要写出来哦。

重要：如果你使用了任何外部来源的代码，或者与其他学生一起合作，却在头部注释里面没有适当的致谢，这可以被认为是抄袭。

命名约定：有意义的名字

对于任何人来说所有咱起的名字都得是有意义的，不管谁读了程序，作者也好，其他人也好，都得能知道这个名字是表达了一个什么内容。
就好比你看到i这个字母的时候，你就会想到他应该是一个数组或者是集合的索引变量，又或者是循环体里面的迭代变量。
使用i和j来表示嵌套循环的话可能会就容易混淆他们两个，用x和y的话更容易区分，但是如果是像遍历一个矩阵这样的行列的情况的话，你完全是可以用row和col来表示行列的。这样反而更明确。

命名约定：大小写和标点

对于标准的Python约定来说，一般是这样的：

local_variable
大部分局部变量名称使用小写，每个词之间使用_来分割。像一些长的变量名，比如rectangle_width，你也可以机智的简写成rect_wid或者rectwid等。

global_variable
在Python里面呀，全局变量和局部变量使用一样的样式。要是这个文章的原作者，他说要是他来写这个规范的话，他会改掉，变成不一样的。我觉得一样的就挺好的啊→_→。

SYMBOLIC_CONSTANT
当全局变量用来表示一个常量的时候（常量就是在你申明的时候就给他付一个值，以后都不会改变了的量），则使用全大写字幕，每个词之间使用一个_来分割。

ClassName
Python使用驼峰法来表示类名，译者补，什么叫驼峰法捏，驼峰法，就是像骆驼的驼峰一样，每个单词之间没有分隔，而且每个单词第一个字母大写，就像骆驼的驼峰一样了~

也许我们会在看别人的程序的时候看到别人的不同的写法，但是请记住，保持好自己的写作风格。

文档注释

文档注释是对Python方法的说明，而且可以整合到Python编程环境里面，比如通过帮助功能。文档注释需要的格式有啥呢？

• 类型契约： 每个参数的类型和返回的类型。
• 方法描述： 对每个参数进行说明，如果有的话，还要对意外情况和返回值进行说明。
• 方法使用的样例。

比如：

  def show_docstring(name) :    '''(str) -> None     Simple hello, world-style function prints hello, name;    None value is returned.    >>> show_docstring('CIS 210')    Hello, CIS 210.    >>> show_docstring('World')    Hello, World.    '''    print('Hello,', name+'.')    return None

对于CIS 2101的方法来说都必须有一个返回说明，哪怕他返回的是None。

写文档注释的时候，需要注意一下几点：
* 一个方法只能返回一种类型的值，就想如果是“当XX情况下返回true”，那么肯定就是“其他情况下返回false”。
* 方法的功能必须完整地在文档中写明确，说白了，如果文档注释中没有说会改变某个参数，那么就改变他。
* 方法必须返回一个值或者是做什么用，两者至少得有一样。

    def maximum(li):        '''(list of ints) -> int        Find and return the maximum integer in li.        >>> maximum(1, 2, 3, 4)        4        >>> maximum(99, 101, 42)        101        '''        sort(li)          return li[-1]

上面的程序实际上是修改了传入参数li的，程序中改变了参数li但是文档注释没有说明，此类情况应该避免。意外的情况要一五一十的说出来。

其他有用的注释

x = x + s         # Adjust for border

在适当的地方加上一些简短的说明文字可以有效地加强代码的可读性。这些注释需要用国际化的英语来书写。所谓的国际化的英语，不是地道的美式英语，也不是阿三咖喱味英语，更不是不列颠口味的英语，更不是开口脆的Chinglish，ジャパンリーシュ就更不是了~！

缩进

记住，每一个级别的缩进都需要使用四个空格（也可以是一个Tab键，其实我更推荐使用一个Tab，毕竟通用……，而且更利于排版）2然后就是千万不要混淆了空格和Tab~千万不要混淆了空格和Tab~千万不要混淆了空格和Tab~！！！！重要的事情要说三遍~！！！！

空格

适当的使用空格来隔开运算符、运算数、符号等等有利于增加代码的可读性。比如：

x=x+1   #Not Recommandx = x + 1   #Recommandif(a>6) #Not Recommandif (a > 6): #Recommand

---

1. CIS 210 就是这个课程的名称，请不要太在意……不过返回为空的时候，也说明的确是一个好习惯。 ↩
2. 这里阐述一下我和原作者不同的意见，原作者表述的是不要使用Tab。。 ↩