我眼中的Python代码规范

Bertha 。 2023-01-12 07:47 132阅读 0赞

### 目录 ###

*  前言
 *  1. 关于注释
 *   *  1.1 开头注释
     *  1.2 单行注释
     *  1.3 多行注释
 *  2. 关于空行
 *   *  2.1 引用空行
     *  2.2 自定义方法的空行
     *  2.3 功能块的空行
 *  3. 关于方法
 *   *  3.1 指明参数类型
     *  3.2 指明返回值类型
 *  4. 关于主函数入口
 *  5. 后记

# 前言 #

“一万个人眼中有一万个哈姆雷特。”这句话用在代码规范上再合适不过了。在没有组织对规范进行限制要求的前提下，由于我们每个人的码风都不一样，所以导致我们的注释也不尽相同。本篇文章谈谈我平时写Python代码的规范，还请各位批评指正。

# 1. 关于注释 #

## 1.1 开头注释 ##

开头注释是指创建Python文件时自动生成的文件头注释。开发者注释不仅是写给我们自己乃至其他人看的，更是给解释器看的。下面是我的开头注释：

# ！/usr/bin/env python
    # -*- encoding: utf-8 -*-
    """
    @Author  : UltraMarine
    @File    : file_name.py
    @Time    : 2021/1/21 18:56
    @Softwire: PyCharm Community Edition 2020.3.2
    """

首先，第一行`# ！/usr/bin/env python`的作用在于，开发者可以直接在命令行通过文件名执行加了该注释的Python文件，否则还需通过关键字python + 文件名才能运行。

第二行的`# -*- encoding: utf-8 -*-`作用在于指定文件的编码方式为utf-8。由于Python3已经支持中文了，所以本行可省略。

之后的多行注释对作者、文件名、创建时间及IDE进行了标注，这些内容主要是给其他人看的，告诉其他人本文件的相关信息。

## 1.2 单行注释 ##

在进行对功能块描述时，我习惯于在第一行语句的上方对其进行简短的描述，常用中文，偶尔用一下英文（有时候英文更合适一点），例如：

# 这是描述代码块功能的单行注释
    代码balabala...

而对于与代码同行的注释，我平时用的比较少，更多的我会选择语句上方的注释。因为开发者更多的是从上往下看代码，便于其理解。

## 1.3 多行注释 ##

除了开头注释，多行注释我几乎只用在方法的描述中：

"""
    简短描述当前方法的功能    
    :param data: 参数描述balabala...
    ...
    :return: 返回值描述balabala...
    """

我只在项目代码中对方法加以注释描述，平日里自己写的小代码没有作过多要求。关于我的方法规范请见下文。

# 2. 关于空行 #

对于何时该空行这个问题，我主要分以下几种种情况：

## 2.1 引用空行 ##

我习惯于将三种引用语句之间空一行加以区分：  
![在这里插入图片描述][20210128022937966.png]  
拿我当前的项目中的某个文件举例。我习惯于将`impor`t语句放于引用块的首部，`import ... as ...` 语句放于中部，`from ... import ...` 放于末尾。同时，我会根据语句的长度进行排序，短的在上面，长一点就放在下面。我认为这样会更加便于管理我的代码。

## 2.2 自定义方法的空行 ##

对于自定义方法的空行，我习惯于在方法的首尾各空两行：

def function1():
    	...
    
    
    def function2():
    	...

我认为方法之间空两行可以很好的区别于方法体内的空一行，同时也让自定义的方法更加明显。

## 2.3 功能块的空行 ##

读到这里可能有的读者会很疑惑：功能块是什么？这个概念其实是我自己拟定出来的。我常习惯于把实现某单一功能的语句块称为一个功能块。

...
    
    # 下一功能块的描述
    ...

对于上一个功能块的结尾，和下一功能块的功能描述注释之间，我会空出一行。这样做可以分割功能块，使代码的各部分功能更加明确。

# 3. 关于方法 #

对于方法的规范，主要在注释、空行、指明参数类型和返回值类型上。前两者已经在前文进行说明，所以接下来对指明参数类型和返回值类型进行介绍，这里拿LeetCode 1. 两数之和的代码模板为例：  
![在这里插入图片描述][20210128024459106.png]

## 3.1 指明参数类型 ##

指明参数类型，实际上就是指明形参的数据类型。如力扣的模板，对每个形参的数据类型进行标注，在调用时出现的代码提示也会帮助你进行使用，可以说是一劳永逸。

## 3.2 指明返回值类型 ##

仅需在声明语句后通过一个箭头，将其指向你所需的返回值的数据类型即可。当用参数接收有返回值的方法时，可以避免一些因参数类型不当导致的一系列问题（当然不写也可以做到）。

# 4. 关于主函数入口 #

对于需要在本文件中运行的文件，我都习惯于添加主函数入口：

if __name__ == '__main__':
    	...

添加主函数入口的目的在于降低自定义方法与当前进程中语句的耦合度，这就要求我在定义方法时将其定义在主函数入口外部，否则高耦合的代码不仅自己写起来难受，别人看起来也难受。

# 5. 后记 #

可能有的读者看完之后，心里只有一个想法：这个人好作哦。

其实，对自己的代码进行规范限制之后，不管是你的编写效率，还是debug效率都会提高很多。而且，在组内分享自己代码时，不会因为码风过丑而被组员“鄙视”。

都说字如其人，字写得好看与否，也能给他人反映出你的性格。代码也是一样，码风的好坏也能向别人反映出一个人的态度高低。一份精良的代码，不仅仅是能取得一个好的运行结果、或是好的性能，更重要的是代码的规范。所以，我更愿意让自己“作”一点。

以上。如各位有更好的建议可以在下方评论区提出，还望各位大佬不吝赐教。

[20210128022937966.png]: /images/20221119/e32184d57b694e48a3b06c940a3b579f.png
[20210128024459106.png]: /images/20221119/c57b4ec0c7594152ab88149cda83403c.png