团队编程项目作业2-团队编程项目代码设计规范

Posted 2020-10-08 GainsLee

命名

文件名、包名、模块名：全小写，使用下划线可以改善可读性可以加入，如my_package。

类：总是使用首字母大写单词串。如MyClass。

函数、方法：函数名应该为小写，可以用下划线风增加可读性，如my_example_function。

变量：小写，尽量避免单字母变量，尽量让变量有意义。

常量：要求全部字幕大写，可以用下划线风增加可读性，如GLOBAL_VAR_NAME。

内部(Internal)：使用(_)开头表示模块变量或函数是protected 的(使用import * from时不会包含)；使用(__)开头表示实例变量或方法表示类内私有，类实例不能调用。

缩写：名中含有长单词，对某个单词进行缩写。这时应使用约定成俗的缩写方式。 例如：function 缩写为 fn；text 缩写为 txt ；object 缩写为 obj ；count 缩写为 cnt；number 缩写为 num 等。

布局

最重要的话写在第一句：如果懒得跟我一样的话，使用pycharm IDE用快捷键Ctrl+Alt+L就可以完成统一的代码布局。

在不使用这个IDE或者忘了用快捷键的情况下，请注意以下统一的代码布局：

代码长度：每行不超过80个字符。这一点pycharm没有这么严格，但是希望大家尽力做到，这样确保其他同事可以轻松愉快地阅读每一行代码。

空行：用两行空行分割顶层函数和类的定义,类内方法的定义用单个空行分割。

缩进：使用4个空格作为一个缩进层次，尽量不要用8个空格。

分号：不要使用分号，尽管是用了也没有错。

括号：括号使用原则是越少越好，不要在返回语句或者条件语句中使用括号，例如：

空格（请尽量不要用制表符TAB，如果用了请保持一致）：

括号内不使用空格；

不在逗号和冒号前使用空格，在其后面添加（跟英文写作一样）；

二元操作符 【赋值(=), 比较(==, <, >, !=, <>, <=, >=, in, notin, is, is not), 布尔(and, or, not)】两边都使用空格，

参数列表里不要带空格

以上截图来自《Google python style guide》

注释

python单行注释用#字符开头即可注释后面的内容，对于重要语句进行注释包括解释说明和提醒的作用。 python多行注释可以用’’’或者”””开头并以相同的用’’’或者”””结尾即可注释多行语句。

特别说明： python的方法内置对象doc String ，它可以用于模块、函数和类的描述，在写方法的时候，只要在方法声明下面进行多行注释。在引用或者使用的场景下，可以通过dir或者help方法可以查看该方法的使用帮助。python的方法注释可以参照下图，pycharm支持自动生成注释，比较方便。

Python 有一种独一无二的的注释方式: 使用文档字符串. 文档字符串是包, 模块, 类或函数里的第一个语句. 这些字符串可以通过对象的__doc__成员被自动提取, 并且被pydoc 所用. (你可以在你的模块上运行pydoc 试一把, 看看它长什么样). 我们对文档字符串的惯例是使用三重双引号. 一个文档字符串应该这样组织: 首先是一行以句号, 问号或惊叹号结尾的概述. 接着是一个空行. 接着是文档字符串剩下的部分, 它应该与文档字符串的第一行的第一个引号对齐。注意上图中的函数注释，文档字符串应该包含函数做什么, 以及输入和输出的详细描述. 通常, 不应该描述”怎么做”, 除非是一些复杂的算法. 对于技巧性的代码, 块注释或者行内注释是最重要的. 文档字符串应该提供足够的信息, 当别人编写代码调用该函数时, 他不需要看一行代码, 只要看文档字符串就可以了. 应该给参数单独写文档. 在冒号后跟上解释,

导入

可以使用两种导入的方法：

1.使用 import x 来导入包和模块。

2.使用 form x import y , 其中x 是包前缀, y 是不带前缀的模块名。

在后面讲述的common-lib库中，建议大家使用from common-lib import *这样的导入，在这个自定义库的__init__.py文件中已经定义了哪些可以导入哪些不需要导入。比较方便。

使用上述的导入方法的时候，要使用绝对路径而非相对路径，避免重复导入。

Main入口

要求所有新建的py文件都要有Main的入口，且必须总是检查该导如的主程序是否被执行。

Pycharm支持python代码模板，建议大家使用这个模板。

#-*- encoding:UTF-8 -*-
from __future__ import division
import sys

__author__ = \'$USER\'
def main():
    pass

if __name__ == \'__main__\':
    reload(sys)
    print "START: system-encoding[%s]"%sys.getdefaultencoding()
    main()

这个代码执行的时候先检查系统的编码，这个TIP是我踩过很多坑之后的教训，这样可以让你每次都知道当前程序运行的编码。