• 首页 > 数据存储频道 > 数据库频道 > 软件架构

    提高Python代码可读性的五个基本技巧

    2022年08月29日 11:06:03   来源:中文科技资讯

      译者 | 赵青窕

      审校 | 孙淑娟

      你是否经常回头看看6个月前写的代码,想知道这段代码底是怎么回事?或者从别人手上接手项目,并且不知道从哪里开始?这样的情况对开发者来说是比较常见的。

      Python中有许多方法可以帮助我们理解代码的内部工作方式,因此当您从头来看代码或者写代码时,应该会更容易地从停止的地方继续下去。

      在此我给大家举个例子,我们可能会得到如下图所示的代码。这还不是最糟糕的,但有一些事情需要我们去确认,例如:

      在load_las_file函数中f和d代表什么?

      为什么我们要在clay函数中检查结果?

      这些函数需要的是什么类型?浮点数还是DataFrames?

      在load_las_file函数中f和d代表什么?

      为什么我们要在clay函数中检查结果?

      这些函数需要的是什么类型?浮点数还是DataFrames?

      在本文中,我将介绍如何通过文档、提示输入和适当的变量名称来提高应用/脚本的可读性的5个基本技巧。

      PART 01

      注释

      我们可以对代码做的第一件事是向某些行添加注释,但是要注意避免注释得过多。注释中需要阐述代码为什么能起作用,或者为什么某些事情要以某种方式完成,而不是它是如何实现的。

      Python中的注释通常使用井号(#)来完成,可以跨一行也可以跨多行。

      # Comment using the hashtag

      # Another comment using the hashtag

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

      """

      This is an example of

      a multi-line comment

      """

      在下面的示例中,代码中添加了一些注释,以解释某些代码行的工作流程和原因:

      PART 02

      显式类型

      Python语言是动态类型的,这意味着变量类型只会在运行时被检查。此外,变量可以在代码执行期间更改类型。另一方面,静态类型涉及显式地声明变量类型,并且在代码执行期间不能更改。

      2014年,PEP 484引入了类型提示的概念,随后这个概念引入到了Python 3.5版本中。这允许您显式地声明变量类型。

      通过添加类型提示,可以显著提高代码的可读性。在下面的例子中,我们可以看出:

      需要两个参数

      参数filename的类型是字符串

      参数start_depth的类型是float类型,同时该参数默认值为None

      该函数将返回一个pandas DataFrame对象

      需要两个参数

      参数filename的类型是字符串

      参数start_depth的类型是float类型,同时该参数默认值为None

      该函数将返回一个pandas DataFrame对象

      根据类型提示,我们可以确切地知道函数需要什么,以及它将返回什么。

      PART 03

      文档字符串

      文档字符串是紧跟在函数或类定义之后的字符串。文档字符串是一种很好的方式,可以详细解释函数的功能、需要什么参数、将引发的异常、返回值等等。

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

      下面的示例显示了名为clay_volume的函数对应的文档字符串。这里我们可以指明每个参数的含义。这使它比基本的类型提示更详细。您还可以包含更多关于函数背后的方法论的信息,如学术参考资料或方程。

      当我们在代码的其他地方调用函数时,文档字符串也是非常有帮助。例如,使用Visual Studio编写代码时,可以将鼠标悬停在函数调用上,然后看到一个弹出窗口,显示函数的功能及其需求。

      如果您使用Visual Studio Code (VS Code)编辑您的Python代码,您可以使用autoDocstring这样的扩展从而使创建文档字符串的过程更容易。您可以输入三个双引号,并自动填充模板的其余部分。你只需要填上细节。

      提示:如果您已经在参数中声明了类型,那么它们将被自动选取。

      PART 04

      具有可读性的变量名

      有时候,当你在写代码的时候,你不会太在意变量的名称,特别是当时间比较紧张的时候。但是,如果您返回看代码时,会发现一系列名为x1或var123的变量,您可能无法一眼理解它们表示什么。

      在下面的例子,有两个变量f和d。我们可以通过查看代码的其他部分来猜测这类变量的含义,但这可能会花费时间,尤其是在代码很长的情况下。

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

      PART 05

      避免魔法数字

      幻数是代码中的值,它们背后有一个无法解释的含义,可以是常量。在代码中使用这些可能会导致歧义,尤其是不熟悉计算中使用数字的情况。此外,如果我们在多个地方有相同的神奇数字,当需要更新它,我们必须更新它的每个实例。然而,如果给这类数字分配一个合适的命名变量,那替换的过程就会容易得多。

      在下面的例子中,我们有一个函数,它计算一个名为result的值,并将其乘以0.6。这是什么意思?它是一个转换因子吗?一个标量吗?

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

      PART 06

      最终代码

      在应用了上面的技巧之后,我们的最终代码现在看起来更清晰,更容易理解。

      PART 07

      总结

      通过注释和文档字符串向代码添加说明有助于帮助您和其他人理解代码正在做什么。一开始可能会觉得这是一件苦差事,但随着工具的使用和定期的练习,它会成为你的第二天性。

      文章内容仅供阅读,不构成投资建议,请谨慎对待。投资者据此操作,风险自担。

    即时探行数字人注册免费试用

    第三代骁龙8s平台,“恰逢其时”的“新生代旗舰”之选

    日前,高通举办新品发布会,推出了骁龙8旗舰移动平台诞生以来的第一款新生代旗舰平台:第三代骁龙8s,这是高通对骁龙旗舰移动平台的一次层级扩展,同时意味着广大消费者未来在旗舰手机市场也将会有更多丰富的选择。

    新闻探行AI智能外呼系统 节省80%人力成本

    敢闯技术无人区 TCL实业斩获多项AWE 2024艾普兰奖

    近日,中国家电及消费电子博览会(AWE 2024)隆重开幕。全球领先的智能终端企业TCL实业携多款创新技术和新品亮相,以敢为精神勇闯技术无人区,斩获四项AWE 2024艾普兰大奖。

    企业IT探行AI客服 24小时无休机器人接待

    重庆创新公积金应用,“区块链+政务服务”显成效

    “以前都要去窗口办,一套流程下来都要半个月了,现在方便多了!”打开“重庆公积金”微信小程序,按照提示流程提交相关材料,仅几秒钟,重庆市民曾某的账户就打进了21600元。

    3C消费探行AI视频 快速生成真人营销视频

    “纯臻4K 视界焕新”——爱普生4K 3LCD 激光工程投影

    2024年3月12日,由爱普生举办的主题为“纯臻4K 视界焕新”新品发布会在上海盛大举行。

    研究探行AI整体解决方案 全国招募代理

    2024全球开发者先锋大会即将开幕

    由世界人工智能大会组委会、上海市经信委、徐汇区政府、临港新片区管委会共同指导,由上海市人工智能行业协会联合上海人工智能实验室、上海临港经济发展(集团)有限公司、开放原子开源基金会主办的“2024全球开发者先锋大会”,将于2024年3月23日至24日举办。