zoukankan      html  css  js  c++  java
  • python 编程的 Style Guide

    Python 的作者既优雅又高冷又 鬼毛的 再 PEP8 里规定了 Python 程序编写规范。(风格和格式)

    一、基本观念

      1、可读性之上,代码被读的次数肯定比被写的次数多。因此作者十分重视代码的可读性,后文中的很多规定都是基于这个出发点考虑的。

      2、一致性次之,如果所有的代码的 style 与本指南不符,有限考虑一致性,但是新编写的模块有限遵风格指南;

    二、具体操作

      1、布局和格式

        +  缩进: 优先用四个空格而不是制表符(tab)

        +  多行连读语句: 对齐。几个正面的例子:

    # 括号内开头对齐
    foo = long_function_name(var_one, var_two,
                             var_three, var_four)
    
    # Hanging indent: 括号第一行不填,第二行开始括号内的部分加倍缩进(多4个空格)
    def long_function_name(
            var_one, var_two, var_three,
            var_four):
        print(var_one)

        + 多行构赋值: 后半括号要独立一行,且和前面的行对齐,两种方式均可:

    my_list = [
        1, 2, 3,
        4, 5, 6,
        ]
    my_list = [
        1, 2, 3,
        4, 5, 6,
    ]

        +  行的长度少于 72 个字符:主要时为了便于分屏对比代码(作者操心命)。

         换行的操作:优先用括号把并列的长语句括起来。然后就可以再连接处换行了,比如 with 或者 assert 语句,再用反斜杠。

        +  在操作符 (+、-、*、)之前换行:方便阅读时快速理解操作符后面的内容是被如何操作的,

        +  空白行:顶层 function 和 class  前后各两行,method 前后各一行

        +  导入 import : 不同的库每个导入各占一行,相同的库里多个模块可以在一行导入,导入顺序: 标准库 -> 空白行,第三方库、本地库

        + 各种符合语句,最好各占一行,为了可读性,不要再一行内出现多个语句

      2、符号

        + 引号:string 的两侧单引号双引号都可以,string 的内容里如果又但单引号,外面的就用双引号,反之亦然,尽量不适用反斜杠类 escape,影响可读性。

        + 空白符:

          1、各种括号的内部不直接用空白符 

    YES: spam(ham[1], {egg: 2})
    No: spam( ham( 1 ), { egg: 2 })

          2、逗号分号冒号前面不直接用空白符

    Yes: if x == 4: print x, y; x, y = y, x
    No:  if x == 4 : print x , y ; x , y = y , x

          3、function 和 variable 名字和括号之间不加空白符

          4、避免在行尾使用多余的空白符,影响某些符号的运行,主要是你很难发现

          5、运算符两端要各加且只加一个空白符,遇到多层优先级的运算,只在最低优先级的运算符两侧加空白符:

    # Yes
    i = i + 1
    submitted += 1
    x = x*2 - 1
    hypot2 = x*x + y*y
    c = (a+b) * (a-b)
    
    # No
    i=i+1
    submitted +=1
    x = x * 2 - 1
    hypot2 = x * x + y * y
    c = (a + b) * (a - b)

          6、关键字参数的赋值等号不用空白符

    def complex(real, imag=0.0):
        return magic(r=real, i=imag)

        +  末尾逗号:tuple 和 list的最后一项是可以接逗号的

            这里说明一下:如果 tuple 和 list 是分行构建的,且每一行左后可以接一个逗号,方便以后的扩展保持统一格式:如果是在同一行构建的,则没必要最后接一个逗号

       3、注释

        +  注释是保证注解的内容保持更新的,不然和代码不符,还真倒不如注释

        +  注释要说人话, 用完整的语句编写,开头大写,句尾加句号

        +  注释据句尾句号后加两个空白符在换行

        +  大段注释,每一行开头 # 开头,几个空白符在写内容,段落之间的空行也用 # 开头

        +  同行注释尽量不使用,干扰阅读代码。如果某些特殊情况必须使用,和代码直接保持两个以上的空白符

        +  docstring : 给所有公开的模块,函数。类写 dcostring. 私有的就不用写了,用注释时代替,

          这种注释应该出现在 def 的后一行,默认用三双引号来做

          docstring : 对于多行的 docstring ,结尾的三引号要独占一行

        4、 命名

          +  命名的风格又很多种,Python 基本使用的是 lower_case_with_underscore

          +  使用 _single_leading_underscore::表示弱的内部使用,在 from X import * 是不会导入这一类对象

          +   使用 single_tailing_underscore_:为了略微改变那些和 Python 的 keyword 冲突的命名

          +   使用__double_leading_underscore:类的外面是无法调用这个对象

          +   首位都有双下划线的命名只限 python 内部使用,不要随意起这种名

          +   不要只用小写的 ”i“ 大写的 ”O“,容易引起误解

          +  package 和 moudle 的命名用 lower_case_with_underscore

          +  类的命名使用 CapWords

          +  Class 内部的命名,能使用非公开就用非公开,因为把一个 attribute 由 非公开变为公开要比反过来容易太多

        5、编程过程中的风格建议

          +   和 None 做比较时永远用 is   is  not 而不是 ==

           +   用 if x in not y 而不是 if not x is y:更贴经自然语言

          +  定义函数的时候,永远用 def 而不是把一个 lambda 函数赋给一个变量名。lambda的唯一使用场景应该是一个复杂的表达里嵌入使用

          +  在使用  Exception 的时候,从 Exception 到处 为不是 BaseException

          + 在使用 try...except ... 排除 意外的时候,明确规定 except 的意外情况而不是直接使用 ‘except’:,这是确保不会把 SystemExit 算进去,那样的话 contrl-c 衲衣操作

          +  保证Return 的一致性:  一个函数里要么都不 return,要么每种情况的 return 都明确规定, 即便return None

    def foo(x):
        if x >= 0:
            return math.sqrt(x)
        else:
            return None
    
    def bar(x):
        if x < 0:
            return None
        return math.sqrt(x)

        +  永远优先使用 string 的 methods 不是直接使用 string module,比如用 .startwith(),  .endwith() 来代替 slicing 作比较

        +    记住空的有序容器比如 tuple set string list 的布尔值是 False 

        +   永远不要把布尔值 和 True / False 作比较,直接用它的真假来控制流程

  • 相关阅读:
    phpdocumentor生成代码注释文档(linux)
    phpstorm扩展
    es教程
    康威定律
    k8s
    tidb调研
    netty 在线教程
    McQueenRPC源码阅读
    DIY一些基于netty的开源框架
    性能测试
  • 原文地址:https://www.cnblogs.com/jcjc/p/11679460.html
Copyright © 2011-2022 走看看