共计 2079 个字符，预计需要花费 6 分钟才能阅读完成。
不晓得小伙伴们是否有这样的困惑，当咱们回顾本人 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。通过代码咱们无奈精确的晓得该段代码的具体含意
如果咱们申明一个变量并将该值调配给它，那么咱们就有更好的机会晓得它是什么。在这种状况下，它是用于将伽马射线指数转换为粘土体积的粘土与页岩的比率。
总结
通过正文和文档字符串将文档增加到咱们的代码中能够大大帮忙本人和其他人理解代码在做什么。的确，一开始可能感觉像是一件苦差事，但通过应用工具和定期练习，它能够成为你的第二天性。
快来整顿你的代码吧~
好了，这就是明天分享的全部内容，喜爱就点个赞吧~
本文由 mdnice 多平台公布
