译者 | 赵青窕
审校 | 孙淑娟
你是否经常回头看看6个月前写的代码，想知道这段代码底是怎么回事?或者从别人手上接手项目，并且不知道从哪里开始?这样的情况对开发者来说是比较常见的。Python中有许多方法可以帮助我们理解代码的内部工作方式，因此当您从头来看代码或者写代码时，应该会更容易地从停止的地方继续下去。
在此我给大家举个例子，我们可能会得到如下图所示的代码。这还不是最糟糕的，但有一些事情需要我们去确认，例如:
- 在load_las_file函数中f和d代表什么?
- 为什么我们要在clay函数中检查结果?
- 这些函数需要的是什么类型?浮点数还是DataFrames？
在本文中，我将介绍如何通过文档、提示输入和适当的变量名称来提高应用/脚本的可读性的5个基本技巧。
1.注释
我们可以对代码做的第一件事是向某些行添加注释，但是要注意避免注释得过多。注释中需要阐述代码为什么能起作用，或者为什么某些事情要以某种方式完成，而不是它是如何实现的。Python中的注释通常使用井号(#)来完成，可以跨一行也可以跨多行。
# Comment using the hashtag
# Another comment using the hashtag
对于多行注释，我们也可以使用双引号。
"""
This is an example of
a multi-line comment
"""
在下面的示例中，代码中添加了一些注释，以解释某些代码行的工作流程和原因：
2.显式类型
Python语言是动态类型的，这意味着变量类型只会在运行时被检查。此外，变量可以在代码执行期间更改类型。另一方面，静态类型涉及显式地声明变量类型，并且在代码执行期间不能更改。
2014年，PEP 484引入了类型提示的概念，随后这个概念引入到了Python 3.5版本中。这允许您显式地声明变量类型。通过添加类型提示，可以显著提高代码的可读性。在下面的例子中，我们可以看出:
- 需要两个参数
- 参数filename的类型是字符串
- 参数start_depth的类型是float类型，同时该参数默认值为None
- 该函数将返回一个pandas DataFrame对象
根据类型提示，我们可以确切地知道函数需要什么，以及它将返回什么。
3.文档字符串
文档字符串是紧跟在函数或类定义之后的字符串。文档字符串是一种很好的方式，可以详细解释函数的功能、需要什么参数、将引发的异常、返回值等等。此外，如果使用Sphinx之类的工具为代码创建在线文档，文档字符串将自动提取并转换为适当的文档。下面的示例显示了名为clay_volume的函数对应的文档字符串。这里我们可以指明每个参数的含义。这使它比基本的类型提示更详细。您还可以包含更多关于函数背后的方法论的信息，如学术参考资料或方程。
当我们在代码的其他地方调用函数时，文档字符串也是非常有帮助。例如，使用Visual Studio编写代码时，可以将鼠标悬停在函数调用上，然后看到一个弹出窗口，显示函数的功能及其需求。
如果您使用Visual Studio Code (VS Code)编辑您的Python代码，您可以使用autoDocstring这样的扩展从而使创建文档字符串的过程更容易。您可以输入三个双引号，并自动填充模板的其余部分。你只需要填上细节。
提示：如果您已经在参数中声明了类型，那么它们将被自动选取。
4.具有可读性的变量名
有时候，当你在写代码的时候，你不会太在意变量的名称，特别是当时间比较紧张的时候。但是，如果您返回看代码时，会发现一系列名为x1或var123的变量，您可能无法一眼理解它们表示什么。在下面的例子，有两个变量f和d。我们可以通过查看代码的其他部分来猜测这类变量的含义，但这可能会花费时间，尤其是在代码很长的情况下。
如果我们为这些变量指定适当的名称，我们将能够知道其中一个变量是由lasio.read()调用读取的data_file，并且很可能是原始数据。data变量告诉我们这是我们正在处理的实际数据。
5.避免魔法数字
幻数是代码中的值，它们背后有一个无法解释的含义，可以是常量。在代码中使用这些可能会导致歧义，尤其是不熟悉计算中使用数字的情况。此外，如果我们在多个地方有相同的神奇数字，当需要更新它，我们必须更新它的每个实例。然而，如果给这类数字分配一个合适的命名变量，那替换的过程就会容易得多。在下面的例子中，我们有一个函数，它计算一个名为result的值，并将其乘以0.6。这是什么意思?它是一个转换因子吗?一个标量吗?
如果我们声明一个变量并将该值赋给它，那么我们就更有可能知道它是什么。在这种情况下，将伽马射线指数转换为粘土体积所用的是粘土与页岩的比值。
6.最终代码
在应用了上面的技巧之后，我们的最终代码现在看起来更清晰，更容易理解。
7.总结
通过注释和文档字符串向代码添加说明有助于帮助您和其他人理解代码正在做什么。一开始可能会觉得这是一件苦差事，但随着工具的使用和定期的练习，它会成为你的第二天性。
原文链接：https://towardsdatascience.com/5-essential-tips-to-improve-the-readability-of-your-python-code-a1d5e62a4bf0
译者介绍
赵青窕，51CTO社区编辑，从事多年驱动开发。研究兴趣包含安全OS和网络安全领域，发表过网络相关专利。
