一、变量与注释决定第一印象
1、变量和注释是代码里最接近自然语言的部分,其可读性至关重要。
2、即便是同一个算法,变量和注释的不同,也会给人截然不同的印象。
二、基础知识
1、Python变量赋值语法非常灵活!
(1)变量解包
动态解包语法中,只要使用星号表达式*variables
作为变量名,就可以贪婪地捕获多个值对象,并将捕获到的内容已链表的形式赋值给variables
。
data = ['sam', 'apple', 'banana', 'orange', 100]
user_name, *fruit_names, cnt = data
print(furit_names)
此时,输出的结果为:
[ 'apple', 'banana', 'orange']
(2)单下划线变量名
下划线_
既可以作为衣蛾个无意义的占位符用于接受变量,在Python交互式命令行中还默认保存了我们输入的上一个表达式的返回值:
>>> 'foo'.upper()
'FOO'
>> print(_)
FOO
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工匠——案例、技巧与工程实践》