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

不知道小伙伴们是否有这样的困惑，当我们回顾自己 6 个月前编写的一些代码时，往往会看的一头雾水，或者是否当我们接手其他人的代码时， Python 中有许多方法可以帮助我们理解代码的内部工作原理，良好的编程习惯，可以使我们的工作事半功倍！ 例如，我们最终可能会得到看起来很像下图中的代码。虽然不是最糟糕的，但是，我们需要扩展一些事情，例如： - load_las_file 函数中的 f 和 d 代表什么？ - 为什么我们要在 clay 函数中检查结果？ - 这些函数需要什么类型？ Floats? DataFrames? ![](https://upload-images.jianshu.io/upload_images/5803165-7ae55662502d49b0.png) 在本文中，我们将着重讨论如何通过文档、提示输入和正确的变量名称来提高应用程序/脚本的可读性的五个基本技巧。 ## 1. Comments 我们可以对我们的代码做的第一件事是为我们的代码添加某些注释，但是却不能过度使用它。注释应该告诉你为什么代码可以工作或者为什么某事以某种方式完成，而不是它是如何工作的。 Python 中的注释通常使用井号 (#) 来完成，并且可以跨越单行或多行。 ```Python # Comment using the hashtag # Another comment using the hashtag ``` 对于多行注释，我们也可以使用三个双引号。 ```Python """ This is an example of a multi-line comment """ ``` 在下面的示例中，代码中添加了一些注释，以解释某些代码行背后的工作流程和推理 ![](https://upload-images.jianshu.io/upload_images/5803165-7e37099a3f285a26.png) ## 2. Explicit Typing Python 语言是动态类型的，这意味着变量类型只会在运行时检查。此外，变量可以在代码执行期间更改类型。 另一方面，静态类型涉及明确说明变量是什么类型，并且在代码执行期间不能更改。 2014 年，PEP 484 引入了类型提示的概念，后来在 Python 3.5 版本中引入，这些允许我们明确说明变量应该是什么类型。 通过添加类型提示，可以显著提高代码的可读性。在下面的例子中，我们可以轻松得到如下信息： - 函数需要两个参数 - 文件名参数应该是字符串类型 - start_depth 参数应该是 float 类型，默认值为 None - 该函数将返回一个 pandas DataFrame 对象 ![](https://upload-images.jianshu.io/upload_images/5803165-a116b42a44e268de.png) 我们可以立即根据类型提示准确判断函数需要什么以及它将返回什么。 ## 3. Docstrings (Documentation Strings) 文档字符串是紧跟在函数或类定义之后的字符串文字，Docstrings 是一个很好的方式来详细解释我们的函数做什么，它需要什么参数，它会引发的任何异常，它会返回什么等等。 此外，如果我们使用 Sphinx 之类的工具为代码创建在线文档，则文档字符串将自动被拾取并转换为适当的文档。 下面的示例显示了一个名为 `clay_volume` 的函数的文档字符串。 在这里，我们可以指定每个参数是什么，这比基本的类型提示更加详细，我们还可以包含有关函数背后的方法的更多信息，例如学术参考或方程式。 ![](https://upload-images.jianshu.io/upload_images/5803165-06974b2f1ee143d9.png) 当我们从代码中的其他地方调用函数时，拥有文档字符串也是非常有帮助的。例如，使用 Visual Studio 编辑代码时，可以将鼠标悬停在函数调用上，然后查看该函数的功能及其要求的弹出窗口。 ![](https://upload-images.jianshu.io/upload_images/5803165-7a447bf16955dc29.png) 如果使用 Visual Studio Code (VSCode) 来编辑我们的 Python 代码，可以使用像 autoDocstring 这样的扩展插件来简化创建文档字符串的过程。该插件允许我们输入三个双引号并自动填充模板的其余部分，我们只需要关注必须填写的其他详细信息即可。 ![](https://upload-images.jianshu.io/upload_images/5803165-5302e36545cab10e.png) ## 4. Readable Variable Names 很多时候，当我们编写代码时，不会太在意变量的名称，尤其是当我们急于完成某些功能时。但是如果我们的代码返回一系列名为 x1 或 var123 的变量，那么可能任谁都无法第一眼理解它们所代表的含义。 下面的示例，我们有两个变量 f 和 d。可以通过查看代码的其他部分来猜测这些含义，但这需要一定的时间，尤其是在代码很长的情况下。 ![](https://upload-images.jianshu.io/upload_images/5803165-bed51aac8f6e73e1.png) 如果我们为这些变量分配适当的名称，就能够知道其中一个是由 lasio.read() 调用读取的 data_file，并且很可能是原始数据，data 变量告诉我们这是我们正在使用的实际数据。 ![](https://upload-images.jianshu.io/upload_images/5803165-0875df70cbd4989d.png) ## 5. Avoiding Magic Numbers 魔法数字是代码中的值，它们背后具有很多无法解释的含义，并且可以表示常量。在代码中使用这些可能会导致歧义，尤其是对于那些不熟悉其中使用数字的任何计算的人。 此外，如果我们在多个地方有相同的魔法数字并且需要更新它，我们将不得不更新它的每个实例。然而如果将数字分配给正确命名的变量，则整个过程会容易得多。 在下面的示例中，我们有一个函数计算一个名为 result 的值并将其乘以 0.6。 通过代码我们无法准确的知道该段代码的具体含义 ![](https://upload-images.jianshu.io/upload_images/5803165-1a20371578e5a5d8.png) 如果我们声明一个变量并将该值分配给它，那么我们就有更好的机会知道它是什么。在这种情况下，它是用于将伽马射线指数转换为粘土体积的粘土与页岩的比率。 ![](https://upload-images.jianshu.io/upload_images/5803165-797c9afe72fc6f0a.png) ## 总结 通过注释和文档字符串将文档添加到我们的代码中可以大大帮助自己和其他人了解代码在做什么。确实，一开始可能感觉像是一件苦差事，但通过使用工具和定期练习，它可以成为你的第二天性。 快来整理你的代码吧~ 好了，这就是今天分享的全部内容，喜欢就点个赞吧~ 本文由[mdnice](https://mdnice.com/?platform=6)多平台发布
©著作权归作者所有,转载或内容合作请联系作者
  • 人面猴
    序言：七十年代末，一起剥皮案震惊了整个滨河市，随后出现的几起案子，更是在滨河造成了极大的恐慌，老刑警刘岩，带你破解...
    沈念sama阅读 202,529评论 5赞 475
  • 死咒
    序言：滨河连续发生了三起死亡事件，死亡现场离奇诡异，居然都是意外死亡，警方通过查阅死者的电脑和手机，发现死者居然都...
    沈念sama阅读 85,015评论 2赞 379
  • 救了他两次的神仙让他今天三更去死
    文/潘晓璐 我一进店门，熙熙楼的掌柜王于贵愁眉苦脸地迎上来，“玉大人，你说我怎么就摊上这事。” “怎么了？”我有些...
    开封第一讲书人阅读 149,409评论 0赞 335
  • 道士缉凶录：失踪的卖姜人
    文/不坏的土叔 我叫张陵，是天一观的道长。 经常有香客问我，道长，这世上最难降的妖魔是什么？ 我笑而不...
    开封第一讲书人阅读 54,385评论 1赞 273
  • 港岛之恋（遗憾婚礼）
    正文 为了忘掉前任，我火速办了婚礼，结果婚礼上，老公的妹妹穿的比我还像新娘。我一直安慰自己，他们只是感情好，可当我...
    茶点故事阅读 63,387评论 5赞 364
  • 恶毒庶女顶嫁案：这布局不是一般人想出来的
    文/花漫 我一把揭开白布。 她就那样静静地躺着，像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上，一...
    开封第一讲书人阅读 48,466评论 1赞 281
  • 城市分裂传说
    那天，我揣着相机与录音，去河边找鬼。 笑死，一个胖子当着我的面吹牛，可吹牛的内容都是我干的。 我是一名探鬼主播，决...
    沈念sama阅读 37,880评论 3赞 395
  • 双鸳鸯连环套：你想象不到人心有多黑
    文/苍兰香墨 我猛地睁开眼，长吁一口气：“原来是场噩梦啊……” “哼！你这毒妇竟也来了？” 一声冷哼从身侧响起，我...
    开封第一讲书人阅读 36,528评论 0赞 256
  • 万荣杀人案实录
    序言：老挝万荣一对情侣失踪，失踪者是张志新（化名）和其女友刘颖，没想到半个月后，有当地人在树林里发现了一具尸体，经...
    沈念sama阅读 40,727评论 1赞 295
  • 护林员之死
    正文 独居荒郊野岭守林人离奇死亡，尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 35,528评论 2赞 319
  • 白月光启示录
    正文 我和宋清朗相恋三年，在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 37,602评论 1赞 329
  • 活死人
    序言：一个原本活蹦乱跳的男人离奇死亡，死状恐怖，灵堂内的尸体忽然破棺而出，到底是诈尸还是另有隐情，我是刑警宁泽，带...
    沈念sama阅读 33,302评论 4赞 318
  • 日本核电站爆炸内幕
    正文 年R本政府宣布，位于F岛的核电站，受9级特大地震影响，放射性物质发生泄漏。R本人自食恶果不足惜，却给世界环境...
    茶点故事阅读 38,873评论 3赞 306
  • 男人毒药：我在死后第九天来索命
    文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹，春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 29,890评论 0赞 19
  • 一桩弑父案，背后竟有这般阴谋
    文/苍兰香墨 我抬头看了看天上的太阳。三九已至，却和暖如春，着一层夹袄步出监牢的瞬间，已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,132评论 1赞 259
  • 情欲美人皮
    我被黑心中介骗来泰国打工， 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留，地道东北人。 一个月前我还...
    沈念sama阅读 42,777评论 2赞 349
  • 代替公主和亲
    正文 我出身青楼，却偏偏与公主长得像，于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子，可洞房花烛夜当晚...
    茶点故事阅读 42,310评论 2赞 342

推荐阅读更多精彩内容