【python简洁之道】-----1. 注释规则

every blog every motto: You will never know unless you try

0. 前言

题外话： 初学python时，老师也教了一些代码规范，起初写代码也是不以为意。过段时间以后再重新看自己代码，内心是……（我的天，这是什么狗屎，……），还有就是看别人写的代码，内心……，慢慢意识到规范代码的重要性。其中注释是代码规范的基础。

whatever，从此刻开始，一起努力。拒绝狗屎，拥抱优雅的代码！，你我的代码都可以很优雅！！！

说明： 本系列专栏，主要讲解有关python规范。想法由来已久，一直没有动手，下面开始第一篇----注释规则

1. 正文

1.1 行注释

“#”后空一格，可写在语句上方 或，后面。一般语句（或注释）较短，注释写在语句右边；语句（或注释）较长，注释写在语句上方。具体如下图所示：
说明： 注释写在语句后方时，“#”和代码空两格！！

if array_channel == 0:  # 如果是第一个通道，要新建数组（5888,5888,10）
	H = arr.shape[0]  # 图像的长 5888
	W = arr.shape[1]  # 图像的宽 5888

# 加载数据，返回投影，几何信息，图片数组(5888,5888,10)
projection, transform, img_arry = self.load_img_to_array(img_input_path)

1.2 块注释

每行以“#”开头，如下图：

# 块注释
# 块注释
#
# 块注释
# 块注释

# load all relevent bands of a image file
# input:
        imgFile: image file
# output:
#         prj: projection data
#         trans: transform data
#         matImg: matrix containing the bands of the image

1.3 函数（文档）注释（Docstring)

当程序写的较长时，在函数间来回跳跃查看函数的具体信息是一件非常麻烦的事，规范添加注释，能够快速查看函数的信息。

• 作为文档的Docstring 一般出现在模块的头部、函数、和类的头部，这样python中可以通过对象的doc对象获取文档
• 编辑器和IDE也可以根据Docstring给出自动提示
• 文档注释以"""（三个双引号）开头和结尾。
• 函数定义完成以后再写注释
  小技巧： 函数定义完成，在函数的第一行，输入三对双引号，自动生成一段固定格式的注释，只需向其中填充必要信息即可。

1.3.1 具体步骤

第一步：输入三对双引号
下方红线为光标所在位置

第二步：按下回车
自动生成固定格式，只需向其中填写必要信息即可。

第三步：填写信息

最终代码，如下。

def load_img_to_array(self, img_file_path):
    """
     读取栅格数据，将其转换成对应数组
     :param: img_file_path: 栅格数据路径
     :return: 返回投影，几何信息，和转换后的数组(5888,5888,10)
     """
     print('这是代码句')
     print('这是代码句')
     print('这是代码句')

1.3.2 快速查看注释（规范注释代码的好处）

将光标放在函数调用的函数名上，按下Ctrl + Q ，能够快速显示函数的信息，如下图：
这样就不用跑到函数定义的地方去查看这个函数事干嘛的了，是不是很方便，有么有！！！！

1.3.3 更进一步（2020.10.13 11:32增补）

更加规范的应该是在说明和参数之间空一行，这样代码更加规范（不会将参数混在说明中，如上图所示），具体如下图：
说明： pycharm2020.2.3(最新版）更加方便丝滑，推荐使用！

1.4 段注释

说明： 这里是我个人的经验，不像上面的几条都是约定俗成的，还请斟酌。
当一个函数定义较长时，函数内部又能分为几部分，可以用三对单引号，注释其中的每一部分。
附： 为了便于展示，将下方的部分代码进行了折叠。

1.4.2 更进一步（2020.11.11增补）

对于一小段代码，实现一个特点的小功能，可以使用这样方式，推荐使用

# -------------------------------
print('这是代码块')
print('这是代码块')
print('这是代码块')
# --------------------------------

例：
如下所示，这样的代码块看起来更加清晰！推荐使用

print('之前操作')

# ------------------------------------------------------------------------
# 保存验证集上的summary(loos,accurcy)
with valid_writer.as_default():
    tf.summary.scalar('loss', t_val_loss.mean(), step=epoch)
    tf.summary.scalar('accuracy', val_acc.numpy(), step=epoch)

# 重置准确度
accuracy.reset_states()
accuracy_val.reset_states()
# ------------------------------------------------------------------------

print('之后操作')

1.5 重要代码注释

在重要代码或是比较复杂的地方，一般使用多个”=“隔开，可以更加醒目。具体如下图：

app = create_app(name, options)


# =====================================
# 请勿在此处添加 get post等app路由行为 !!!
# =====================================


if __name__ == '__main__':
    app.run()

1.6 快速规范代码

在Pycharm中，可以使用Ctrl + Alt + L ，快速规范代码使其符合PEP8的规范，当然只是调整空行、空格一类，并不会帮你添加注释。

参考文献

[1] https://www.jianshu.com/p/5ea95e6cf8e4