pep8编码规范

文档地址

1. pep8（python代码样式规范）文档地址(中文)
2. pep257（Python文档字符串相关的约定）文档地址
3. pep20 (python的禅宗)文档地址

代码样式规范 （pep8）

1.行缩进：tab（4个空格）

• 隐式行连接缩进

  • 1、对齐
  • 2、层级缩进
  • 3、

  # 对齐缩进
  # 对齐缩进
  foo = dict(name="MuSen", age=18,
             gender="男", height="180")
  
  
  # 层级缩进(为了区别应当再缩进四格)
  def fun_add(
          a, b=200,
          c=1000, d=2000):
      return a, b, c, d
  
  
  # 行连线 
  with open("txt1.txt") as f1,
       open("txt2.txt") as f2:
      f1.read()
      f2.read()
  

2. 单行字符限制

• 所有行限制的最大字符数为79个
• 没有结构化限制的大块文本（文档字符或者注释），每行最大字符数限制在72

3. 空行

• 顶级函数和类的定义之间有两行空行
• 类内部的函数定义之间有一个空行

4. 源文件编码方式

• Python核心发布中的的代码应该始终UTF-8（Python2中默认是ASCII编码）
• Python3中不应该有编码声明

5. 注释

1、与代码组矛盾的注释比没有注释还糟，代码有更新，更新对应的的注释！

2、如果注释很短，结尾句号可以省略。块注释一般由完整句子的一个或多个段落组成，并且每句话结束有个句号。在句尾结束的时候应该使用两个空格

3、在非英语国家的Python程序员，请使用英文写注释，除非你120%的确信你的代码不会被其他语言的人阅读----忽略

• 行内注释

  • 行内注释和代码至少要有两个空格分离
  • 注释由#和一个空格开始，有节制的使用

  a = 6
  print(a)  # 打印a
  

• 块注释

  • 块注释通常使用与跟随他们的某些（或全部）代码，并锁紧到与代码相同的级别。
  • 块注释的每一行开头使用一个#和一个空格（除非块注释内部缩进文本）
  • 块注释的段落通过只有一个#的空行分割。

  def add_num(a, b, c):
      # 此函数的功能式返回三个数字和
      # 
      # 简单明了
      return a + b + c
  

6. 文档注释PEP 257描述写出的文档相关的约定

• 文档注释应当使用：三个双引号 ""xxxx """来包裹
• 要为所有的公共的模块、函数、类便携文档说明
• 非公共的方法没有必要添加文档注释，但应该有一个描述方法具体作用的注释，这个注释应该在def那一行之后

def add_num(a, b, c):
    '''
    这是一个计算的方法
            
    :param a: int
    :param b: int
    :param c: int
    :return:
    '''
    return a + b + c

• 单行文档注释："""数值""" 引号文字同一行
• 多行文档注释：多行文档字符串由一个摘要组成，就像一行文档字符串，后跟一个空行，后面是更详细的描述，多行文档说明使用结尾三引号独立 一行
• 提取文档的注释：对象的__doc__属性

import requests

print(requests.__doc__)

7. 模块和包相关规范

• 位置：导入文娱文件的顶部，在文档注释之后，在模块全局变量之前

• 导入顺序

  • 1、标准库导入
  • 2、相关的第三方库导入
  • 3、特定本地应用库导入

• 模块的内置属性（名字前后双下划线）

  • 例如：__all__*,__author__,__version__,应该放在模块的文档注释之后，任意import，from 语句之前

  """
  第一先文档注释
  第二__all__双下滑先
  第三 import
  第四 全局变量
  """
  __all__ = {}
  
  import requests
  
  a = 5
  
  
  # 推荐
  import os
  import requests
  from subprocess import Popen, PIPE
  
  # 不推荐
  from requests import get
  import requests,os
  from requests import *  # 中毒禁忌
  
  

8. 命名规范

• 变量命名
  • 永远不要用字母"l""(小写的L)"O"(大写的O)作为单字符变量
  • 在某些字体里面无法和数字0和1区分
• 函数命名
  • 函数名应该小写，用下滑线分割
  • 大小写混合仅在为了兼容已存在的代码的风格使用，保持向后兼容性
• 类命名
  • 类名一般使用首字母大写的约定
  • 在接口被文档化并且要被用于调用的情况下么可以使用函数的命名风格代替
  • 对于内置的变量命名有一个单独的约定：大部分内置变量是单个单词（或者两个单词连接在一起），首字符大写的命名只用于异常名或者内部变量
• 类里面函数和参数
  • 始终要将self作为实例方法的第一个参数
  • 始终要将cls作为类静态方法的第一个参数
  • 如果函数的参数名和已有的关键词冲突，在最后单一下划线比缩写或者随意拼写更好，class_比cla更好
• 包和模块
  • 模块的命名要短
  • 使用小写
  • 避免使用特殊字符
  • 尽量保持模块名简单，以无需分开单词命名（不推荐使用两单词之间下划线分开）
• 常量
  • 通常定义与模块级别并且所有的字母都是大写、单词用下划线分开

9.项目结构价绍

• readme：对项目的整体介绍，同时也是一份使用手册，需要时常维护更新，通常为README.rst/README.md
• LICENSE:简述该项目许可说明和授权
• setup.py：通过setup把核心代码打包发布
• sample：存放项目核心代码
• requirements.txt：存放该项目所有依赖的第三方库
• docs：包的参考文档
• tests：所有的代码测试都存在于该目录下
• makefile：用于项目的命令管理（开源项目比较广泛）根据项目需求添加其他文件和目录