简介:为什么要强调 书写规范 ?这其实并不关乎“美丑”,而是为了 更高的效率(代码阅读、开发、维护)与更方便的合作(全球通用的标准) 。如今,不管什么方向的同学都要进行“写代码”这项工作,可惜的是,很多朋友并没有意识到:花费1小时了解代码书写规范,可以为自己节省 100+ 小时的写代码的时间。 代码规范的魅力在于 实实在在地简化问题 ,并不需要我们奉为圭臬或引起争论。本文我们主要以 python 为例,以 pep8 为主要参考资料,分三个层次进行讨论。
本文三个层次:
import tkinter
import tkinter.messagebox
def message_box(error_content):
top = tkinter.Tk() # *********
top.withdraw() # ****实现主窗口隐藏
top.update() # *********需要update一下
txt=tkinter.messagebox.showinfo("提示",error_content)
top.destroy()
return txt
上述是在用 python
的 tkinter
做一个桌面应用,看起来似乎没什么问题?大问题,比如项目逻辑/设计架构 的确难以通过这么几行代码看出来 ;但是,上面这几行代码的书写习惯,反映了一个人的思维不够成熟:
# ****
这么书写,完全没必要需要update一下
这是废话,前面不就是 update()
函数吗?("提示",error_content)
中间应该打空格txt=tkinter
左右两边应该加空格如果让现在的我来写,我会如下实现:
import tkinter
from tkinter import messagebox as msg
def show_message_box(error_content):
"""
Piper蛋窝:
输入错误信息,messagebox 显示信息
(皮一下:欢迎关注 Piper蛋窝~)
"""
tk = tkinter.Tk()
tk.withdraw()
tk.update()
txt = msg.showinfo("提示", error_content)
tk.destroy()
return txt
如上:
message_box
改为了 show_message_box
,因为 message_box
看起来像一个名词,并不是动词(去执行一项任务),在项目结构复杂后,我们可能有很多函数、类、实例,如果 不做动名词区分,我们自己都可能混淆,还要翻回源码进行查阅,浪费大量时间"""注释"""
里,这样解释器与 InelliSense 会在我们调用时,做自动的说明,如下图如图,调用时智能地显示我们的注释
朋友,如果你写代码时连 缩进、命名与空间
这三点都不会注意到,那恭喜你,这篇文章很有可能让你提升一个阶段。
我就见过刚刚学 c 的大一小朋友,在机房的 VC 6 里一个一个地敲下字符:
#include <stdio.h>
int main()
{int a=5,b=7,c;
printf("a=%d,b=%d,c=%d",a,b,c);
return 0;}
很显然,这位小朋友的代码真的仅仅是“敲进电脑的字符”而已,ta心里完全没有程序的逻辑、层次。这代码是死的,不是活的。我仅仅加一些空格和回车,来解释, 为什么这些缩进、命名与空间让代码成为真正的代码 。
#include <stdio.h>
int main()
{
int a = 5, b = 7, c;
printf("a = %d, b = %d, c = %d", a, b, c);
return 0;
}
如上:
{}
独立,并对其中代码块做了缩进,表示这些代码是函数 main()
内部的逻辑a=5
变成了 a = 5
,是因为程序员也是人,也需要读看得清晰的东西#include <stdio.h>
与 int main()
间加了空行,因为这二者是两件事:前者负责引入io标准库,后者负责执行逻辑。 在写代码时,不要吝啬空行,来区分不同的逻辑与任务上面的讨论是不是过于基础?下面我们以 python 以及其官方文档 pep 8 为例,来看看更多体现程序逻辑、增强代码可读性的官方建议。
如果下回有人再让你看ta写的“死代码”,你先把这篇文章扔给ta,让ta改好!
著名美剧《硅谷》里有个情节, 程序员会因为使用制表符还是空格吵得不可开交,似乎是一个原则性问题?
这当然只是玩笑。
在 python 中,推荐使用 4 个空格来进行缩进。我在打 kdd cup 是见过 2 个空格表示缩进的(官方 start toolkit 里)。我觉得这是无所谓的,关键是, 你要在项目里进行统一。
此外, 缩进是用来体现程序结构的,如果你的结构不是包含关系,仅仅是换行,那么也用 4 个空格缩进将很愚蠢。 如下。
# 推荐
foo = long_function_name(var_one, var_two,
var_three, var_four)
# 或者
foo = long_function_name(var_one, var_two,
var_three, var_four)
# 或者
foo = long_function_name(var_one, var_two,
var_three, var_four)
# 或者
def long_function_name(
var_one, var_two, var_three,
var_four):
print(var_one)
# 愚蠢
foo = long_function_name(var_one, var_two,
var_three, var_four)
# 愚蠢
def long_function_name(
var_one, var_two, var_three,
var_four):
print(var_one)
为什么?我们以最下面的 def long_function_name
为例,注意到了吗:
print(var_one)
应该是 def long_function_name
的内部结构,因此必须比 def long_function_name
前多一个缩进var_one, var_two, var_three
这些参数是 def long_function_name
的一部分,与 def long_function_name
同级因此,你只需要 制造区分度 就可以。至于你是多加两个空格,还是减少两个,这个无所谓(除非你们组织做了特定的规定), 能让你和别人一眼看出逻辑结构就好 。
此外, pep 8 还推荐了 operator 的位置,这个我以前真的没有注意到。
# No: operators sit far away from their operands
income = (gross_wages +
taxable_interest +
(dividends - qualified_dividends) -
ira_deduction -
student_loan_interest)
# Yes: easy to match operators with operands
income = (gross_wages
+ taxable_interest
+ (dividends - qualified_dividends)
- ira_deduction
- student_loan_interest)
此外,为了防止编译错误,我会在换行时加上 \
表示将换行键转义。
income = (gross_wages \
+ taxable_interest \
+ (dividends - qualified_dividends) \
- ira_deduction \
- student_loan_interest)
现在看来,可能这种情况下没有这个必要。
Yes: spam(ham[1], {eggs: 2})
No: spam( ham[ 1 ], { eggs: 2 } )
Yes: if x == 4: print x, y; x, y = y, x
No: if x == 4 : print x , y ; x , y = y , x
如上是 Pet Peeves 中的建议,很显然,过于松散的结构,也不利于我们阅读和看出逻辑。这是一种所有编程语言通用的习惯,值得养成。
# Yes
def complex(real, imag=0.0):
return magic(r=real, i=imag)
# No
def complex(real, imag = 0.0):
return magic(r = real, i = imag)
如上,在定义某个省缺值时,我们鼓励去掉 =
左右的空格。
# Yes
def munge(sep: AnyStr = None): ...
def munge(input: AnyStr, sep: AnyStr = None, limit=1000): ...
# No
def munge(input: AnyStr=None): ...
def munge(input: AnyStr, limit = 1000): ...
但是,如上,值得注意的是,如果定义了函数的数据类型(如 AnyStr
),则我们需要提醒开发者注意区分,不要去掉 =
左右的空格。
Yes: import os
import sys
No: import sys, os
# Yes
i = i + 1
submitted += 1
x = x*2 - 1
hypot2 = x*x + y*y
c = (a+b) * (a-b)
# No
i=i+1
submitted +=1
x = x * 2 - 1
hypot2 = x * x + y * y
c = (a + b) * (a - b)
关于 import 的规范有几条,我这里着重强调一个新手可能都会有的“坏习惯”: 把毫不相干的库放在一个 import 下。
图什么呢?没有任何意义。比如上面,sys
其实与 os
没有任何包容关系,我们何必吝啬这一行 import
呢?且放在一起,不利于 formatter
帮我们整理书写。
不同的企业/组织,尤其是大型的企业,会有一套自己的命名规范。对于 java ,我记得大家最常用的应该是“驼峰”式命名:
public void printUserName(int index) {
...
}
在 python ,鼓励各种通用形式的命名,如:
printUserName
print_user_name
我觉得大家在 python 中最常用的是 下划线+小写 的形式。
在 pep 8 的 Descriptive: Naming Styles 有个标注,很搞笑:
Capitalized_Words_With_Underscores (ugly!)
为什么说 Capitalized_Words_With_Underscores
“丑”呢?
我觉得是 信息冗余 了:下划线或者大写首字母,都是用于间隔单词的,两个都使用,真的不简洁、不优雅。
在 C++ 或者 java 中,我们都会接触到 private
这类概念。初学者可能会一头雾水:为什么变量要分为私有的、公共的、受保护的?
python 让初学者避开了这部分可能产生的费解,但是又没有去掉私有变量等功能,我觉得这正是 pythonic 的体现。 而且,现在的语言都有此趋势,比如 go
,限制首字母大小写区分变量私有共有,简洁优雅,又统一了社区开发规范。
对于 python ,我们在变量前加了两个下划线,则其变为私有了。私有变量为了项目的规范与安全,不能被外部调用,我写了一段程序如下。
如上,直接调用 Foo.__a
或者 foo.__b
会产生 AttributeError 错误。但是 python 给了个“后门”,你仍然可以通过 _类名__变量名
调用私有变量。
# Yes
if foo is not None:
# No
if not foo is None:
如上,或许新手会觉得 not ... is
这种结构逻辑来了个反转,很好玩,尽管其作用与 is not
完全相同。
还是那句话,程序员也是人,大家都喜欢简单清晰的逻辑。除非是很巧妙的技巧,否则,没有必要玩文字游戏,降低效率。
我们知道, pep 8 希望我们每行 最多 79 个字符。
我觉得对于我这种开发者来说,真的没必要。而且,我读过很多优秀的开源框架,其也没有尊重这个标准。
原因很简单,我们的生产环境不同。
我喜欢大字体,而且我只有一个小小的笔记本电脑,连工位都没有。 很多朋友拥有好几块屏幕/加长屏幕,而我只能把一块小小的笔记本显示器竖着一分为二。如下图。
无论是 79 个字符,还是 109 个字符,我的编辑器都不能一行显示下来,因此这条规范对我来说意义不大。
或许开发 python 标准库时会用上。但不是现在。
pep 8 与 pep 257 中,都对注释方式进行了标准化,如下。
def complex(real=0.0, imag=0.0):
"""Form a complex number.
Keyword arguments:
real -- the real part (default 0.0)
imag -- the imaginary part (default 0.0)
"""
if imag == 0.0 and real == 0.0:
return complex_zero
...
我并不是很感兴趣。原因:
如上是 thu-ml/tianshou 源码,其注释使用 markdown 写的, 如果去访问说明文档,你会发现说明文档就是根据源代码注释自动生成的。
Amazing. 这才是“写代码的”该有的美德:懒惰,不做重复的动作,能自动化就自动化。
最后,光说不练假把戏。
在我看来,多读优秀的代码、项目, 有意识地注意高手的书写规范和其怎么安排项目结构,意义远比只读 pep 8 要大很多。
Piper蛋窝
,回复微信
加我微信。欢迎点赞
、点击在看
鼓励我。手机扫一扫
移动阅读更方便
你可能感兴趣的文章