不知道小伙伴们是否有这样的困惑，当我们回顾自己 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。通过代码我们无法准确的知道该段代码的具体含义
如果我们声明一个变量并将该值分配给它，那么我们就有更好的机会知道它是什么。在这种情况下，它是用于将伽马射线指数转换为粘土体积的粘土与页岩的比率。
总结
通过注释和文档字符串将文档添加到我们的代码中可以大大帮助自己和其他人了解代码在做什么。确实，一开始可能感觉像是一件苦差事，但通过使用工具和定期练习，它可以成为你的第二天性。
快来整理你的代码吧~
