Python代码注释规范代码实例解析

一、代码注释介绍

  • 注释就是对代码的解释和说明，其目的是让人们能够更加轻松地了解代码。
  • 注释是编写程序时，写程序的人给一个语句、程序段、函数等的解释或提示，能提高程序代码的可读性。
  • 在有处理逻辑的代码中，源程序有效注释量必须在20％以上。

二、代码注释分类

行注释：在符号后那一行不会被编译（显示）

块注释：被块注释符号中间的部分不会被编译

三、python代码注释基础

Python中使用#表示单行注释。单行注释可以作为单独的一行放在被注释代码行之上，也可以放在语句或表达式之后。如下例子：

name = 'xiaohong' # 单行注释

# 单行注释
name = 'xiaohong'

Python中使用三个单引号或三个双引号表示多行注释。用在注释多写不下的情况，如下例子：

'''
这是使用三个单引号的多行注释
'''

"""
这是使用三个双引号的多行注释
"""

四、DocStrings介绍与使用

4.1 DocStrings介绍

文档字符串

是一个重要工具，用于解释文档程序，帮助你的程序文档更加简单易懂

4.2 python中使用DocStrings

在函数体的第一行使用一对三个单引号 ''' 或者一对三个双引号 """ 来定义文档字符串。你可以使用 doc（注意双下划线）调用函数中的文档字符串属性。

编写示例如下：

def add(num1,num2):
  """ 完成传入的两个数之和

  :param num1: 加数1
  :param num2: 加数2
  :return: 和
  """
  return num1 + num2

print( add.__doc__ )

备注：DocStrings 文档字符串使用惯例：它的首行简述函数功能，第二行空行，第三行为函数的具体描述。

五、DocStrings常用编写风格

5.1 reST风格

这是现在流行的一种风格，reST风格，Sphinx的御用格式，比较紧凑。

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

5.2 Google风格

"""
This is a groups style docs.

Parameters:
 param1 - this is the first param
 param2 - this is a second param

Returns:
 This is a description of what is returned

Raises:
 KeyError - raises an exception
"""

5.3 Numpydoc (Numpy风格)

"""
My numpydoc description of a kind
of very exhautive numpydoc format docstring.

Parameters
----------
first : array_like
 the 1st param name `first`
second :
 the 2nd param
third : {'value', 'other'}, optional
 the 3rd param, by default 'value'

Returns
-------
string
 a value in a string

Raises
------
KeyError
 when a key error
OtherError
 when an other error
"""

六、一些注释经验

  • 注释不是越多越好。对于一目了然的代码，不需要添加注释。
  • 对于复杂的操作，应该在操作开始前写上相应的注释。
  • 对于不是一目了然的代码，应该在代码之后添加注释。
  • 绝对不要描述代码。一般阅读代码的人都了解Python的语法，只是不知道代码要干什么

以上就是本文的全部内容，希望对大家的学习有所帮助，也希望大家多多支持我们。

赞 (0)

相关推荐

  • Python实现判断一行代码是否为注释的方法

    目前的编辑器大都可以自动检测某一行代码是否为代码行或注释行,但并不太提供代码行/注释行行数的统计,对于大量代码文件的代码行/注释行统计,就更少见一些.本篇文章试用一段Python脚本来实现这一目标,并希望可以兼容统计不同语言编写的代码. 注释符号的研究 我们先来关注常见语言的注释符号构成.一般来讲注释符号分为单行注释符和多行注释符,以Python为例,则分别为#和'''(或""").由于多行注释符会影响后续行的判断,所以在遍历各行时必须存在一个标志位multiCmtFlagI

  • 在Python的Django框架中为代码添加注释的方法

    就像HTML或者Python,Django模板语言同样提供代码注释. 注释使用 {# #} : {# This is a comment #} 注释的内容不会在模板渲染时输出. 用这种语法的注释不能跨越多行. 这个限制是为了提高模板解析的性能. 在下面这个模板中,输出结果和模板本身是 完全一样的(也就是说,注释标签并没有被解析为注释): This is a {# this is not a comment #} test. 如果要实现多行注释,可以使用`` {% comment %}`` 模板标

  • 使用python制作游戏下载进度条的代码（程序说明见注释）

    使用python制作游戏下载进度条的代码（程序说明见注释）

    import time # time模块中包含了许多与时间相关的模块,其中通过time()函数可以获取当前的时间. count = 100 print("开始下载".center(100, '-')) start = time.perf_counter() # 通过time()函数可以获取当前的时间并付给变量start for i in range(count + 1): a = "■" * i # 用■的个数来具体化已经下载完的进度.■在输入法里的特殊符号里. b

  • 将python代码和注释分离的方法

    python的注释方式和C语言.C++.java有所不同 python语言中,使用'#' 来进行注释,其次还有使用 三个引号来进行注释 本文的程序将把 python 中 使用'#' 号 好 三个引号的注释分离出来, 当然也能再次合并回去 有需求的小伙伴可以来围观了 #!/usr/bin/python #coding=utf-8 import os import sys reload(sys) sys.setdefaultencoding('utf-8') class Comment_Filter

  • python代码如何注释

    注释 注释就是对代码的解释和说明.目的是为了让别人和自己很容易看懂.为了让别人一看就知道这段代码是做什么用的.正确的程序注释一般包括序言性注释和功能性注释.序言性注释的主要内容包括模块的接口.数据的描述和模块的功能.模块的功能性注释的主要内容包括程序段的功能.语句的功能和数据的状态. 注释的分类 1.单行注释 以#开头,#右边的所有东西当做说明,而不是真正要执行的程序,起辅助说明作用 #我是注释,可以在这里写一下功能说明之类 print("我上面一行是对我的注释") 2.多行注释 多行

  • Python统计python文件中代码,注释及空白对应的行数示例【测试可用】

    本文实例讲述了Python实现统计python文件中代码,注释及空白对应的行数.分享给大家供大家参考,具体如下: 其实代码和空白行很好统计,难点是注释行 python中的注释分为以#开头的单行注释 或者以'''开头以'''结尾 或以"""开头以"""结尾的文档注释,如: ''' hello world ''' 和 ''' hello world''' 思路是用is_comment记录是否存在多行注释,如果不存在,则判断当前行是否以'''开头,是则

  • python matplotlib 注释文本箭头简单代码示例

    python matplotlib 注释文本箭头简单代码示例

    注释文本箭头 结果展示: 完整代码示例: import numpy as np import matplotlib.pyplot as plt fig, ax = plt.subplots(figsize=(5, 5)) ax.set_aspect(1) x1 = -1 + np.random.randn(100) y1 = -1 + np.random.randn(100) x2 = 1. + np.random.randn(100) y2 = 1. + np.random.randn(100

  • 用python统计代码行的示例(包括空行和注释)

    实例如下所示: import os import string path = "/Users/U/workspace/python learning/show-me-the-code/0007/test/" dir = os.listdir(path) def count(file): total = 0 #总行数 countPound = 0 #注释行数 countBlank = 0 #空行数 line = open(file,'r',encoding='utf-8') #打开文件,

  • Python代码注释规范代码实例解析

    一.代码注释介绍 注释就是对代码的解释和说明,其目的是让人们能够更加轻松地了解代码. 注释是编写程序时,写程序的人给一个语句.程序段.函数等的解释或提示,能提高程序代码的可读性. 在有处理逻辑的代码中,源程序有效注释量必须在20%以上. 二.代码注释分类 行注释:在符号后那一行不会被编译(显示) 块注释:被块注释符号中间的部分不会被编译 三.python代码注释基础 Python中使用#表示单行注释.单行注释可以作为单独的一行放在被注释代码行之上,也可以放在语句或表达式之后.如下例子: name

  • Python3打包exe代码2种方法实例解析

    这篇文章主要介绍了Python3打包exe代码2种方法实例解析,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下 cx_Freeze(不推荐) 以前只用 cx_Freeze 支持将 python3 打包成 exe ,示例如下: 在你要打包的 python 文件下新建这个 setup.py 文件: #!/usr/bin/env python # -*- coding: utf-8 -*- from cx_Freeze import setup, Ex

  • Java代码注释规范详解

    Java代码注释规范详解

    代码附有注释对程序开发者来说非常重要,随着技术的发展,在项目开发过程中,必须要求程序员写好代码注释,这样有利于代码后续的编写和使用. 基本的要求: 1.注释形式统一 在整个应用程序中,使用具有一致的标点和结构的样式来构造注释.如果在其它项目中发现它们的注释规范与这份文档不同,按照这份规范写代码,不要试图在既成的规范系统中引入新的规范. 2.注释内容准确简洁 内容要简单.明了.含义准确,防止注释的多义性,错误的注释不但无益反而有害. 3.基本注释(必须加) (a) 类(接口)的注释 (b) 构造函

  • Java代码注释规范(动力节点整理)

    代码注释是架起程序设计者与程序阅读者之间的通信桥梁,最大限度的提高团队开发合作效率.也是程序代码可维护性的重要环节之一.所以我们不是为写注释而写注释.下面说一下我们在日常开发中使用的代码注释规范,供大家参考下. 1. 注释形式统一 在整个应用程序中,使用具有一致的标点和结构的样式来构造注释.如果在其它项目中发现它们的注释规范与这份文档不同,按照这份规范写代码,不要试图在既成的规范系统中引入新的规范. 2. 注释内容准确简洁 内容要简单.明了.含义准确,防止注释的多义性,错误的注释不但无益反而有害

  • python并发编程之线程实例解析

    python并发编程之线程实例解析

    常用用法 t.is_alive() Python中线程会在一个单独的系统级别线程中执行(比如一个POSIX线程或者一个Windows线程) 这些线程将由操作系统来全权管理.线程一旦启动,将独立执行直到目标函数返回.可以通过查询 一个线程对象的状态,看它是否还在执行t.is_alive() t.join() 可以把一个线程加入到当前线程,并等待它终止 Python解释器在所有线程都终止后才继续执行代码剩余的部分 daemon 对于需要长时间运行的线程或者需要一直运行的后台任务,可以用后台线程(也称

  • python re模块findall()函数实例解析

    本文研究的是re模块findall()函数的相关内容,首先看看实例代码: >>> import re >>> s = "adfad asdfasdf asdfas asdfawef asd adsfas " >>> reObj1 = re.compile('((\w+)\s+\w+)') >>> reObj1.findall(s) [('adfad asdfasdf', 'adfad'), ('asdfas asd

  • Python中实现switch功能实例解析

    前言 今天在学习python的过程中,发现python没有switch这个语法.于是就想在python中如何才能实现这个功能呢? 正文 本文中我们对switch的使用模拟为正常的数据库的增删改查操作的对应,如'select 对应'select action'等. 1.简单的if-else 正如我们所知,python中有if语句,而且当时学习C的时候,学到if-else时引出的的替代品就是switch,两者可以完美的互相替代,需要注意的是在python中else if简化成了elif.如下所示:

  • python使用锁访问共享变量实例解析

    本文研究的主要是python使用锁访问共享变量,具体介绍和实现如下. python 做多线程编程时,多个线程若同时访问某个变量,可能会对变量数据造成破坏,pyhon中的threading模块提供了lock对象,lock中的acquire方法用于获取一个锁,而release用于释放一个锁.当一个线程取得锁时,它变获得了共享变量的访问权,此时进入阻塞状态,若其它线程申请访问这个变量,则必须等到这个线程调用release方法释放这个锁.下面是python中使用锁的实例: #!/usr/bin/env

  • Python使用Pandas读写Excel实例解析

    这篇文章主要介绍了Python使用Pandas读写Excel实例解析,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下 Pandas是python的一个数据分析包,纳入了大量库和一些标准的数据模型,提供了高效地操作大型数据集所需的工具. Pandas提供了大量能使我们快速便捷地处理数据的函数和方法. Pandas官方文档:https://pandas.pydata.org/pandas-docs/stable/ Pandas中文文档:https:/

  • Python zip函数打包元素实例解析

    这篇文章主要介绍了Python zip函数打包元素实例解析,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下 介绍 zip() 函数用于将可迭代的对象作为参数,将对象中对应的元素打包成一个个元组,然后返回由这些元组组成的列表. ps. 如果各个迭代器的元素个数不一致,则返回列表长度与最短的对象相同,利用 * 号操作符,可以将元组解压为列表. 例子 a = [1,2,3] b = [4,5,6] c = [4,5,6,7,8] zipped = zi

随机推荐