当前位置:   article > 正文

【python简洁之道】-----1. 注释规则_python注释是上下还是左右

python注释是上下还是左右

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
  • 1
  • 2
  • 3
# 加载数据,返回投影,几何信息,图片数组(5888,5888,10)
projection, transform, img_arry = self.load_img_to_array(img_input_path)
  • 1
  • 2

1.2 块注释

每行以“#”开头,如下图:

# 块注释
# 块注释
#
# 块注释
# 块注释
  • 1
  • 2
  • 3
  • 4
  • 5
'
运行
# 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
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7

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
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9

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('这是代码块')
# --------------------------------
  • 1
  • 2
  • 3
  • 4
  • 5
'
运行

例:
如下所示,这样的代码块看起来更加清晰!推荐使用

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
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14

1.5 重要代码注释

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

app = create_app(name, options)


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


if __name__ == '__main__':
    app.run()
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10

1.6 快速规范代码

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

参考文献

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

声明:本文内容由网友自发贡献,不代表【wpsshop博客】立场,版权归原作者所有,本站不承担相应法律责任。如您发现有侵权的内容,请联系我们。转载请注明出处:https://www.wpsshop.cn/w/盐析白兔/article/detail/904518
推荐阅读
相关标签
  

闽ICP备14008679号