Python中的变量与注释

一、变量与注释决定第一印象

1、变量和注释是代码里最接近自然语言的部分，其可读性至关重要。
2、即便是同一个算法，变量和注释的不同，也会给人截然不同的印象。

二、基础知识

1、Python变量赋值语法非常灵活！

（1）变量解包
动态解包语法中，只要使用星号表达式*variables作为变量名，就可以贪婪地捕获多个值对象，并将捕获到的内容已链表的形式赋值给variables。

data = ['sam', 'apple', 'banana', 'orange', 100]
user_name, *fruit_names, cnt = data
print(furit_names)
1
2
3

此时，输出的结果为：

• [ 'apple', 'banana', 'orange']

（2）单下划线变量名
下划线_既可以作为衣蛾个无意义的占位符用于接受变量，在Python交互式命令行中还默认保存了我们输入的上一个表达式的返回值：

>>> 'foo'.upper()
'FOO'
>> print(_)
FOO
1
2
3
4

2、编写注释的要点

• 不要用注释来屏蔽代码，该删除就删除；
• 注释是用来解释“为什么”、而不是用来复述，代码应当具有自解释性；

3、接口注释不要包含内部细节

接口注释是为使用者而撰写的，因此应当简明扼要的描述函数职责，而不必包含太多的方法内部细节。

4、可以用Sphinx格式文档或类型注解给变量标明类型

三、变量命名很重要

1、遵守PEP8原则

• 普通变量采取蛇形命名法，max_value
• 常量采取全部大写字母，MAX_VALUE
• 仅内部使用，为其增加下划线前缀，_local_var
• 与Python关键字冲突，在末尾添加下划线后缀，class_

2、描述性要强

在变量长度允许的范围内，变量名所指向的内容描述越准确越好。
当然，变量的命名需要考虑其使用场景，例如value作为描述性较弱的命名法，就很适合某个数学公式的计算结果。

3、要尽量短

利用结合上下文语境的方法，尽量缩短变量命名长度，一般不要超过4个单词，否则就会显得啰嗦。

4、要匹配类型

• 布尔类型
  使用is、has、allow等；

• int / float类型

  • 释义为数字的单词，例如port、age、redius等；
  • 以_id为结尾的单词，例如user_id等；
  • 以length、count开头或结尾的单词；

5、可以使用一两个字母的超短命名法，但不要过度使用

6、其他技巧

• 在同一段代码中，不要出现多个相似的变量命名，例如：user1、user2、user3；
• 可以尝试更换单次表达，来简化复合变量名，；例如用is_special替代is_not_normal；

四、代码组织技巧

1、按照代码的职责组织代码：让变量定义靠近使用

不要在方法一开始就将所有变量定义好，什么时候用、什么时候再去定义。

2、适当定义临时变量可以提升代码可读性

很多时候我们会有一个非常长的if判断条件或表达式，这个时候我们可以抽象出一个新的可读性强的变量来接收判断条件。
直接翻译业务的代码往往不是好的代码，优秀的程序设计要从原始需求分解的基础上，进行恰到好处的抽象，这样才能满足可读性和可扩展性的要求。

3、不必要的变量会让代码冗余、啰嗦

很多时候，我们定义了一个变量后，紧接着就将其return了，这种情况下变量没有使用、也没有被编辑，完全是冗余的。

4、同一作用于内不要有太多变量

正如一个函数长度不应该超过50行，一个方法内部也不应该有太多的参数。
当出现参数过多的问题，一般可以通过将数据建模提炼为类，或者拆分函数来进行解决。

5、空行也是一种“注释”，适当的空行可以让代码更易读

在函数内部的段落间按照逻辑块，使用空行进行区分，能够很大程度提高整体的可读性。

五、代码可维护性技巧

1、保持变量的一致性

• 名字一致性
• 类型一致性

2、显式优于隐式：不要用locals()

虽然locals()方法能批量获取当前作用域所有局部变量，但看似简洁的背后，却是要求代码阅读者记住所有的变量！
“Python之禅”中有一句：

• Explicit is better than implicit，显式优于隐式，很好的说明了问题

3、把接口注释当成一种函数设计工作

先写接口注释，再去写代码。如果你无法用一句有说服力的注释说明接口，就别写任何函数代码：此时的接口设计一定是混乱、冗余的。

参考内容：《Python工匠——案例、技巧与工程实践》