Python文件头部规范注释与省略内容杂记

Posted 许硕的博客

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了Python文件头部规范注释与省略内容杂记相关的知识,希望对你有一定的参考价值。

文件头部规范

Python相关文档(官方文档):2. Python 解释器 — Python 3.11.2 文档

  • 第一行(可选):#!/usr/bin/python#!/usr/bin/python3#!/usr/bin/env python#!/usr/bin/env python3

通常,以“#!”开头的代码行叫做 Shebang ,用于指定Linux、macOS等系统运行文件的终端。(Windows会自动忽略)

  • 第二行(可选,如果没有上述第一行的话就可以将此行作为文件第一行):

可以用类似# -*- coding: encoding -*-的形式指定编码,如使用# -*- coding: utf-8 -*-指定此文件的编码为UTF-8

注释

  • 单行注释:#。如下——
# 我是一个单行注释!
# Python解释器会自动跳过注释而并不会执行它!
  • 多行注释:\'\'\' \'\'\'""" """。如下——
\'\'\'
我是一个多行注释!
Python解释器会自动跳过注释而并不会执行它!
\'\'\'

"""
我是一个多行注释!
Python解释器会自动跳过注释而并不会执行它!
"""
  • 多行注释补充:多行注释只是一个名称,实际上,它也可以只写一行。如下——
\'\'\' 没想到吧!我还可以这样~ \'\'\'

""" 没想到吧!我还可以这样~ """

省略内容

  • pass常用于省略需要填写内容但并无可填内容的地方。如(如下定义一个空函数):
def func():
    pass
  • Ellipsis(“...”)与pass差不多,但它在IDLE界面有文字回显。相较pass来说,pass体现的是“永久空缺”,即以后不会修改此部分内容;但Ellipsis(“...”)表现的是“临时空缺”,即当前功能还未完善,待以后更新。如(如下定义一个空类):
class demo:
    ...
  • Ellipsis(“...”)补充:除此之外,“...”这个符号有时在某些特殊情况也会表示某个对象“它自己”,如下:
a = [1,2,3]
a[1] = a
print(a) # [1, [...], 3]

Python PEP8 编码规范 注释

  与代码相矛盾的注释比没有注释还糟,当代码更改时,优先更新对应的注释! 
  注释应该是完整的句子。如果一个注释是一个短语或句子,它的第一个单词应该大写,除非它是以小写字母开头的标识符(永远不要改变标识符的大小写!)。 
  如果注释很短,结尾的句号可以省略。块注释一般由完整句子的一个或多个段落组成,并且每句话结束有个句号。 
  在句尾结束的时候应该使用两个空格。 
  当用英文书写时,遵循Strunk and White (译注:《Strunk and White, The Elements of Style》)的书写风格。 
  在非英语国家的Python程序员,请使用英文写注释,除非你120%的确信你的代码不会被使用其他语言的人阅读。

块注释

  块注释通常适用于跟随它们的某些(或全部)代码,并缩进到与代码相同的级别。块注释的每一行开头使用一个#和一个空格(除非块注释内部缩进文本)。 
  块注释内部的段落通过只有一个#的空行分隔。、

行内注释

  有节制地使用行内注释。 
  行内注释是与代码语句同行的注释。行内注释和代码至少要有两个空格分隔。注释由#和一个空格开始。 
  事实上,如果状态明显的话,行内注释是不必要的,反而会分散注意力。比如说下面这样就不需要:

x = x + 1                 # Increment x

但有时,这样做很有用:

x = x + 1                 # Compensate for border

文档字符串 

  • 要为所有的公共模块,函数,类以及方法编写文档说明。非公共的方法没有必要,但是应该有一个描述方法具体作用的注释。这个注释应该在def那一行之后。
  • PEP 257 描述了写出好的文档说明相关的约定。特别需要注意的是,多行文档说明使用的结尾三引号应该自成一行,例如:
"""Return a foobang

Optional plotz says to frobnicate the bizbaz first.
"""
  • 对于单行的文档说明,尾部的三引号应该和文档在同一行。

 









以上是关于Python文件头部规范注释与省略内容杂记的主要内容,如果未能解决你的问题,请参考以下文章

Python:如何在省略注释的同时从属性文件创建字典

Python编码规范杂记(很乱:))

python杂记

VS Code 中配置新建 Python 文件自动添加头部注释

python杂记

php编程规范