提高Python代码可读性的5个技巧分享

目录
  • 1. Comments
  • 2. Explicit Typing
  • 3. Docstrings (Documentation Strings)
  • 4. Readable Variable Names
  • 5. Avoiding Magic Numbers
  • 总结

不知道小伙伴们是否有这样的困惑,当我们回顾自己 6 个月前编写的一些代码时,往往会看的一头雾水,或者是否当我们接手其他人的代码时,

Python 中有许多方法可以帮助我们理解代码的内部工作原理,良好的编程习惯,可以使我们的工作事半功倍!

例如,我们最终可能会得到看起来很像下图中的代码。虽然不是最糟糕的,但是,我们需要扩展一些事情,例如:

  • load_las_file 函数中的 f 和 d 代表什么?
  • 为什么我们要在 clay 函数中检查结果?
  • 这些函数需要什么类型? Floats? DataFrames?

在本文中,我们将着重讨论如何通过文档、提示输入和正确的变量名称来提高应用程序/脚本的可读性的五个基本技巧。

1. Comments

我们可以对我们的代码做的第一件事是为我们的代码添加某些注释,但是却不能过度使用它。注释应该告诉你为什么代码可以工作或者为什么某事以某种方式完成,而不是它是如何工作的。

Python 中的注释通常使用井号 (#) 来完成,并且可以跨越单行或多行。

# Comment using the hashtag
# Another comment using the hashtag

对于多行注释,我们也可以使用三个双引号。

"""
This is an example of
a multi-line comment
"""

在下面的示例中,代码中添加了一些注释,以解释某些代码行背后的工作流程和推理

2. Explicit Typing

Python 语言是动态类型的,这意味着变量类型只会在运行时检查。此外,变量可以在代码执行期间更改类型。

另一方面,静态类型涉及明确说明变量是什么类型,并且在代码执行期间不能更改。

2014 年,PEP 484 引入了类型提示的概念,后来在 Python 3.5 版本中引入,这些允许我们明确说明变量应该是什么类型。

通过添加类型提示,可以显著提高代码的可读性。在下面的例子中,我们可以轻松得到如下信息:

  • 函数需要两个参数
  • 文件名参数应该是字符串类型
  • start_depth 参数应该是 float 类型,默认值为 None
  • 该函数将返回一个 pandas DataFrame 对象

我们可以立即根据类型提示准确判断函数需要什么以及它将返回什么。

3. Docstrings (Documentation Strings)

文档字符串是紧跟在函数或类定义之后的字符串文字,Docstrings 是一个很好的方式来详细解释我们的函数做什么,它需要什么参数,它会引发的任何异常,它会返回什么等等。

此外,如果我们使用 Sphinx 之类的工具为代码创建在线文档,则文档字符串将自动被拾取并转换为适当的文档。

下面的示例显示了一个名为 clay_volume 的函数的文档字符串。

在这里,我们可以指定每个参数是什么,这比基本的类型提示更加详细,我们还可以包含有关函数背后的方法的更多信息,例如学术参考或方程式。

当我们从代码中的其他地方调用函数时,拥有文档字符串也是非常有帮助的。例如,使用 Visual Studio 编辑代码时,可以将鼠标悬停在函数调用上,然后查看该函数的功能及其要求的弹出窗口。

如果使用 Visual Studio Code (VSCode) 来编辑我们的 Python 代码,可以使用像 autoDocstring 这样的扩展插件来简化创建文档字符串的过程。该插件允许我们输入三个双引号并自动填充模板的其余部分,我们只需要关注必须填写的其他详细信息即可。

4. Readable Variable Names

很多时候,当我们编写代码时,不会太在意变量的名称,尤其是当我们急于完成某些功能时。但是如果我们的代码返回一系列名为 x1 或 var123 的变量,那么可能任谁都无法第一眼理解它们所代表的含义。

下面的示例,我们有两个变量 f 和 d。可以通过查看代码的其他部分来猜测这些含义,但这需要一定的时间,尤其是在代码很长的情况下。

如果我们为这些变量分配适当的名称,就能够知道其中一个是由 lasio.read() 调用读取的 data_file,并且很可能是原始数据,data 变量告诉我们这是我们正在使用的实际数据。

5. Avoiding Magic Numbers

魔法数字是代码中的值,它们背后具有很多无法解释的含义,并且可以表示常量。在代码中使用这些可能会导致歧义,尤其是对于那些不熟悉其中使用数字的任何计算的人。

此外,如果我们在多个地方有相同的魔法数字并且需要更新它,我们将不得不更新它的每个实例。然而如果将数字分配给正确命名的变量,则整个过程会容易得多。

在下面的示例中,我们有一个函数计算一个名为 result 的值并将其乘以 0.6。 通过代码我们无法准确的知道该段代码的具体含义

如果我们声明一个变量并将该值分配给它,那么我们就有更好的机会知道它是什么。在这种情况下,它是用于将伽马射线指数转换为粘土体积的粘土与页岩的比率。

总结

通过注释和文档字符串将文档添加到我们的代码中可以大大帮助自己和其他人了解代码在做什么。确实,一开始可能感觉像是一件苦差事,但通过使用工具和定期练习,它可以成为你的第二天性。

到此这篇关于提高Python代码可读性的5个技巧分享的文章就介绍到这了,更多相关Python代码可读性内容请搜索我们以前的文章或继续浏览下面的相关文章希望大家以后多多支持我们!

(0)

相关推荐

  • python使用typing模块加强代码的可读性(实战演示)

    一.需求描述 没有类型提示的编程,总觉得不太方便,好在python3.5以后内置了typing模块. typing模块会对函数和变量类型进行注解. 但是Python 运行时不强制执行函数和变量类型注解,但这些注解可用于类型检查器.IDE.静态检查器等第三方工具. 官方网址: typing --- 类型提示支持 - Python 3.10.1 文档 https://docs.python.org/zh-cn/3/library/typing.html 二.实战演练 1.体验注解功能 如下所示,定义

  • 提高python代码可读性利器pycodestyle使用详解

    目录 关于PEP-8 目的 安装 基本用法 高级用法 结论 编程是数据科学中不可或缺的技能,虽然创建脚本来执行基本功能很容易,但编写大规模可读性良好的代码需要更多的思考. 关于PEP-8 pycodestyle 检查器提供基于 PEP-8 样式约定的代码建议.那么 PEP-8 到底是什么呢? PEP 代表 Python 增强建议,PEP-8 是一个概述编写 Python 代码最佳实践的指南.它的主要目标是通过标准化代码样式来提高代码的整体一致性和可读性. 目的 快速浏览一下PEP-8文档,就会发

  • 分享10提高 Python 代码的可读性的技巧

    目录 1.字符串反转 2.首字母大写 3.查询唯一元素 4.变量交换 5.列表排序 6.列表推导式 7.合并字符串 8.拆分字符串 9.回文串检测 10.统计列表元素出现次数 1. 字符串反转 字符串反转有很多方法,咱们再这里介绍两种:一种是切片,一种是python字符串的reversed方法. # -!- coding: utf-8 -!- string = 'hello world' # 方法1 new_str = string[::-1] ic(new_str) # 方法二 new_str

  • 提高Python代码可读性的5个技巧分享

    目录 1. Comments 2. Explicit Typing 3. Docstrings (Documentation Strings) 4. Readable Variable Names 5. Avoiding Magic Numbers 总结 不知道小伙伴们是否有这样的困惑,当我们回顾自己 6 个月前编写的一些代码时,往往会看的一头雾水,或者是否当我们接手其他人的代码时, Python 中有许多方法可以帮助我们理解代码的内部工作原理,良好的编程习惯,可以使我们的工作事半功倍! 例如,

  • 写好Python代码的几条重要技巧

    程序设计的好与坏,早在我们青葱岁月时就接触过了,只是那是并不知道这竟如此重要.能够立即改善程序设计.写出"好"代码的知识有以下几点: •面向对象五个基本原则: •常见的三种架构: •绘图: •起一个好名字: •优化嵌套的 if else 代码: 当然,其他技术知识的丰富程度也决定了程序设计的好坏.例如通过引入消息队列解决双端性能差异问题.通过增加缓存层提高查询效率等.下面我们一起来看看,上面列出的知识点包含哪些内容,这些内容对代码和程序设计的改善有何帮助. 面向对象五个基本原则 本书作

  • 提升 Python 代码运行速度的6个技巧

    其实,Python 比我们想象的运行的要快.我们之所以有先入为主的认为Python运行慢,可能是我们平常的误用和缺乏使用技巧知识. 接下来让我们看看如何用一些简单的Trick来提高我们程序的运行性能 1.使用内置函数 Python中的许多内置函数都是用C实现的,并且经过了很好的优化.因此,如果熟悉这些内置函数,就可以提高Python代码的性能.一些常用的内置函数有sum().len().map().max()等. 假设我们有一个包含单词的列表,我们希望每个单词的首字母均变为大写.此时使用map(

  • 提高python代码运行效率的一些建议

    1. 优化代码和算法 一定要先好好看看你的代码和算法.许多速度问题可以通过实现更好的算法或添加缓存来解决.本文所述都是关于这一主题的,但要遵循的一些一般指导方针是: 测量,不要猜测. 测量代码中哪些部分运行时间最长,先把重点放在那些部分上. 实现缓存. 如果你从磁盘.网络和数据库执行多次重复的查找,这可能是一个很大的优化之处. 重用对象,而不是在每次迭代中创建一个新对象.Python 必须清理你创建的每个对象才能释放内存,这就是所谓的"垃圾回收".许多未使用对象的垃圾回收会大大降低软件

  • Python中最大最小赋值小技巧(分享)

    码代码时,有时候需要根据比较大小分别赋值: import random seq = [random.randint(0, 1000) for _ in range(100)] #方法1: xmax, xmin = max(seq), min(seq) #方法2: xmax, *_, xmin = sorted(seq) 从上面这个来看,看不出来方法2的优势来,不过我们常用的是比较两个数的大小,并选取: dx, dy = random.sample(seq, 2) #方法1: dx, dy = m

  • Python数据处理的三个实用技巧分享

    目录 1 Pandas 移除某列 2 统计标题单词数 3 Genre 频次统计 我使用的 Pandas 版本如下,顺便也导入 Pandas 库. >>> import pandas as pd >>> pd.__version__ '0.25.1' 在开始前先确保解释器和数据集在同一目录下: >>> import os >>> os.chdir('D://source/dataset') # 这是我的数据集所在目录 >>&

  • 盘点提高 Python 代码效率的方法

    第一招:蛇打七寸:定位瓶颈 首先,第一步是定位瓶颈.举个简单的栗子,一个函数可以从1秒优化到到0.9秒,另一个函数可以从1分钟优化到30秒,如果要花的代价相同,而且时间限制只能搞定一个,搞哪个?根据短板原理,当然选第二个啦. 一个有经验的程序员在这里一定会迟疑一下,等等?函数?这么说,还要考虑调用次数?如果第一个函数在整个程序中需要被调用100000次,第二个函数在整个程序中被调用1次,这个就不一定了.举这个栗子,是想说明,程序的瓶颈有的时候不一定一眼能看出来.还是上面那个选择,程序员的你应该有

  • JavaScript避免代码的重复执行经验技巧分享

    我喜欢到一些大型网站上去翻阅它们的原代码,期望能找到一些可以应用到自己的代码中的模式,或发现一些之前从未听说过的工具和技巧.可是,在我查看这些大型网站的源代码时,经常会发现一个问题,那就是重复的代码执行,重复的功能应用.下面就是一些在查看它们的源代码时发现一些问题,把这些分享给大家,希望能让你们更加简洁高效的写出JavaScript代码. 重复的收集元素 我在他们的JavaScript代码里看到的最常见的问题是重复的收集元素.虽然jQuery选择器引擎或querySelectorAll的执行速度

随机推荐