python基础之注释

1.python基础之注释2023-06-27

2.python语言学习路线（基础）2023-06-26 3.python源码结构2023-06-26 4.python发展史及python应用场景2023-06-26 5.变量2023-06-28 6.bug及debug2023-06-29 7.常见数据类型及其转换2023-06-30 8.字符串格式化2023-06-30 9.转义符2023-06-30 10.字符串在货币、日期、精度的处理2023-07-01 11.字符编解码2023-07-01 12.字符编解码及其相互转换2023-07-01 13.内置函数-help-帮助文档2023-07-01 14.内置函数print-输出2023-07-03 15.内置函数input2023-07-03 16.运算符2023-07-04 17.int的缓存策略（特别容易混）2023-07-04 18.判断语句2023-07-04 19.random模块2023-07-04 20.判断语句+ random的应用-剪刀石头布游戏2023-07-04 21.三元运算符（if else的简写）2023-07-04 22.循环语句-while2023-07-05 23.循环语句-while-练习题2023-07-05 24.循环语句for循环2023-07-05 25.循环语句 + else2023-07-05 26.字符串类str2023-07-06 27.正则在字符串中的简单应用2023-07-06 28.列表（List）2023-07-07 29.列表list的sort方法的坑2023-07-07 30.列表综合应用-8个教室随机分配到3个教室2023-07-08 31.元组2023-07-08 32.自动组包 & 自动解包2023-07-08 33.字典2023-07-08 34.集合2023-07-08 35.公共操作2023-07-08 36.公共操作-推导式（集合、列表、字典）2023-07-08 37.函数定义、调用、闭包2023-07-08 38.拆包和交换变量值2023-07-09 39.函数的变量作用域、返回值、参数2023-07-09 40.函数递归2023-07-09 41.匿名函数（lambda表达式）012023-07-09 42.内置函数abs2023-07-09 43.内置函数round2023-07-09 44.内置函数abs022023-07-09 45.高阶函数2023-07-09 46.内置高阶函数map2023-07-09 47.内置高阶函数reduce2023-07-09 48.内置函数reduce2023-07-09 49.学生管理系统-函数&循环&运算符综合练习2023-07-09 50.文件操作之语法2023-07-10 51.文件操作2-最佳实践2023-07-11 52.文件操作之seek2023-07-11 53.文件及文件夹操作2023-07-11 54.面向对象基本概念2023-07-12 55.面向对象之类、对象的定义2023-07-12 56.添加和获取对象属性2023-07-12 57.面向对象之魔法方法2023-07-12 58.魔法函数 __repr__() 和 __str__()的区别2023-07-12 59.魔法方法__len__2023-07-12 60.魔法方法之__getitem__(self, key)、__setitem__(self, key, value) 和 __delitem__(self, key) 2023-07-12 61.魔法方法之__iter__(self) && __next__(self)2023-07-17 62.TypeError: iter() returned non-iterator of type 'MyIterable'2023-07-17 63.魔法方法之__contains__()2023-07-17 64.魔法方法之__call__2023-07-17 65.魔法方法之__getattr__(), __setattr__(), 和 __delattr__2023-07-18 66.__eq__(), __lt__(), 和 __gt__() 2023-07-18 67.案例：烤地瓜2023-07-18 68.案例：给房子置办家具2023-07-19 69.继承2023-07-19 70.继承之子类复用父类的属性、方法2023-07-19 71.继承的分类2023-07-19 72.MRO2023-07-19 73.继承之子类重写父类同名属性和方法2023-07-19 74.⼦类调⽤⽗类的同名⽅法和属性2023-07-19 75.私有属性&&方法的定义&访问限制2023-07-19 76.setter&getter方法访问私有属性2023-07-20 77.__mro__属性2023-07-20 78.python 面向对象3大特征详解2023-07-20 79. 类属性和实例属性2023-07-21 80.类属性和实例属性最佳实践2023-07-21 81.类方法2023-07-21 82.静态方法2023-07-21 83.异常基础2023-07-21 84.多组异常处理基础2023-07-22 85.多组异常处理2023-07-22 86.使用Python内置的错误信息2023-07-22 87.捕获所有异常2023-07-22 88.手动抛异常（raise）2023-07-22 89.try-except-else-finally2023-07-22 90.断言assert在异常中应用2023-07-22 91.自定义异常类2023-07-22 92.模块2023-07-23 93.常见的5种模块导入2023-07-23 94.模块的定位顺序2023-07-23 95.__all__变量限制、明确导入范围2023-07-23 96.包2023-07-23 97.时间模块datetime2023-07-23 98.多任务编程之并发、并行概念2023-07-23 99.进程实现多任务（进程概念、单进程、多进程执行多任务）2023-07-23

注释的作用

Python 中的注释主要有以下几个作用：

代码解释说明
注释可以对代码进行解释说明，方便其他开发人员和你自己在日后阅读代码时能够更好地理解代码的含义和作用。能够准确理解代码的含义，也会有利于更快地进行代码的修改和维护。
代码调试
注释可以用来暂时禁用一行或多行代码，从而方便进行代码调试或测试。在需要在代码中暂时禁用一些语句或部分代码时，可以将其注释起来，而不必将其删除或者添加条件循环语句等。
生成文档
注释可以用来自动生成文档，方便其他开发人员进行阅读和使用。代码中包含的文档字符串可以通过一些工具自动生成文档，例如 sphinx 等。

因此，在编写代码时，注释是一个很重要的方面，尤其是对于一些规模较大的项目，良好的注释可以减少开发人员的沟通成本，帮助开发人员更好地理解代码和功能。

注释的分类

Python 中的注释主要分为两种类型：单行注释和多行注释。

1. 单行注释

单行注释以 # 开头，用于在代码的同一行内注释说明，如下：　　　　　

# 这是一个单行注释的示例

2. 多行注释（文档注释）

多行注释以三个单引号（'''）或三个双引号（"""）开始和结束，用于在多行代码中注释说明，如下：

'''
这是一个多
行注释的示例
'''

或

"""
这也是一个多
行注释的示例
"""

建议使用单行注释对某行代码进行说明，需要对大段代码进行注释和说明时，使用多行注释。

另外，Python 中还有一种特殊的注释叫做“文档字符串”，也即函数注释，文档字符串以三个单引号或双引号开始和结束，用于对函数、类、模块等进行说明和文档化。例如：

def my_function():
    """
    这是一个函数的文档字符串示例
    """
    print("Hello, world!")

文档字符串虽然不是必需的，但编写文档字符串可以帮助其他开发人员更好地理解你的代码，并且可以通过一些工具自动生成文档，提高代码可读性和维护性。

注释最佳实践/说明

1. python解释器是不执行注释的

2. 单行注释用于对某行代码进行说明，其放在位置有2处：

1. 与代码同行，唯一代码之后。 #与代码空2个空格，#与注释内容空1个空格

2. 注释在代码上方：与代码对齐，与上面代码尽量空1行

3. 注释描述代码功能和作用：对于每个函数，它的输入、输出参数和加工处理的步骤都需要有注释，以便后来的人可以更好地理解代码的作用和效果。在解释函数或代码段时，请确保您清楚而准确地描述了它们的作用。

4. 使用简洁且易于理解的注释：注释应该传达必要的信息，同时不要重复代码功能或显而易见的操作。

5. 注释代码而不是思路：注释应该解释代码而不是该段代码实现的复杂思路。类或函数等的注释应该解释其要解决的问题，而不是实现代码的详细过程。

6. 在需要时加上空行：在一些代码段之间加上一些空行，可以提高代码的可读性，也可以帮助区分代码段和注释。

7. 使用 "docstrings"：Python 有一种特殊的注释叫做 "docstrings"，它们用来描述函数、类、模块等的用途和功能。正确地使用 "docstrings" 可以帮助生成文档和帮助使用者更好地理解代码。

8. 注释要规范、一致且易于维护：注释应该采用一种一致的格式和语法，便于阅读且易于维护。例如使用大写字母来写注释的标题，使用小写字母来写注释的内容。

总之，良好的注释应该能够让其他人甚至自己都更好地理解代码，提高代码的可读性、可维护性和复用性。大厂都是有编码规范的，其中就涉及注释。养成一个好的编码习惯，才不会被鄙视。

示例

 1 '''
 2 模块注释（多行注释）
 3 '''
 4 
 5 print("单行注释，用于对某行代码的说明")  # 单行注释位于代码之后：#号与代码之间空2个空格，#号与注释之间空1个空格
 6 
 7 # 我是单行注释，单行注释位于代码之上，与代码缩进一致，注释与上方代码（print("单行注释，用于对某行代码的说明")）空1行
 8 print("单行注释，用于对某行代码的说明")
 9 
10 '''
11 在这个示例中：
12     1. 函数的文档字符串使用了 "docstrings" 格式，描述了该函数的输入、输出和功能。
13     2. 函数体内使用注释，解释了代码的作用。
14     3. 注释使用了一致的格式和语法，易于阅读。
15     4. 注释描述的是代码的具体实现方式，而不是思路。
16     5. 灵活应用空行，提高了代码可读性。
17 具有很好的可读性以及易于维护和复用的特点
18 '''
19 
20 
21 def add_two_numbers(num1, num2):
22     """
23     This function adds two given numbers together and returns the result.
24 
25     Args:
26         num1 (int or float): the first number to be added
27         num2 (int or float): the second number to be added
28 
29     Returns:
30         int or float: the sum of `num1` and `num2`
31     """
32     # Add the two numbers together and return the result
33     result = num1 + num2
34     return result

posted @ 2023-06-27 00:34 Allen_Hao 阅读(282) 评论(0) 编辑收藏举报

allenxx

python基础之注释

注释的作用

注释的分类

1. 单行注释

2. 多行注释（文档注释）

注释最佳实践/说明

示例

公告

搜索

常用链接

我的标签

合集

随笔分类

随笔档案

阅读排行榜

推荐排行榜