因为代码读的时间比写的时候要多,所以无论从哪个角度说,都应该编写可阅读的代码。好的代码不需要猜,一看就明白。

作者提到增强代码可读性的几个要点:

  • 避免过于简短的变量名
  • 写出你的函数参数名称
  • 为你的类和方法编写文档
  • 注释你的代码
  • 重构代码直到它们变成可读的函数或方法
  • 保持函数或方法的简短。一个经验法则是阅读函数或方法的代码不需要滚动屏幕

一个简短的变量名可能省下几秒钟输入时间,可是后面可能让你猜一个钟头,所以这种缩写不值得。

最后一条有例外没有?有,高手懂得规则,又不会死板的被规则束缚。但是在打破规则之前,要知道你自己在做什么。记得github上有个项目,有个核心的模块,代码就是一个巨长版本的函数。作者在开头就说明:我知道自己在做什么,你们不要尝试重构修改。因为代码功能充分内聚,考虑了所有的可能及其处理,必须如此才能达到高效应用的结果。

《三体》里面的章北海就是一个典型人物。他知道规则,平实也认真遵守规则。但是关键时刻也会毫不犹豫的打破规则,不被它束缚。

PEP 8

Python社区有个PEP 8代码规范,应该阅读并且尽量遵守。更方便的是,很多好的IDE已经支持PEP 8代码检查,如果不符合规范,会自动的标记、提示。写代码,要用最好的工具,别听那些“最好的程序员用记事本”这种笨蛋才信的说法。最好的程序员不吝惜使用最好的电脑,最好的代码库,最好的IDE,最好的辅助工具,因为这些东西都可以提升工作效率。

书中推荐了一个工具:flake8,这是一个命令行代码检查工具:

http://flake8.pycqa.org/en/latest/

PEP 8规范建议每行代码长度不超过79个字符。但是依照现在显示器的技术进步 – 分辨率比过去的设备高得多,可以放宽到99个字符长度。

Imports 规范

  • 建议的import顺序

标准库 -> 相关第三方库 -> 本地库、自定义库

  • 使用显式相对包引入

这个有点儿拗口,如果不明白,参考《Python学习手册》578页的说明。简而言之,是使用如下方式的包引入形式:

from .models import spam

注意from后面的“.”,这个符号改变了原本的包搜索路径,改为从当下目录搜索。或者看下面的说明:

The Definitive Guide to Python import Statements

Absolute vs Relative Imports in Python

显式相对包引入,减少了包冲突的机会,降低了维护需求。

 

  • 避免使用import *

这个了解Python语言机制的人会理解:import * 容易污染覆盖当前的代码空间,引发隐秘的bug。正确的做法是使用哪个,就引入哪个。

  • 参考Django代码规范

代码规范主要看方便合理和接受程度。Django也有自己的一套规范,在这里

书中主要提到:使用“_”,不要用“-”,除了URL本身。

  • 选择 JS,HTML,CSS代码规范

可以理解,不同领域的事情,习惯是不一样的。在这些领域工作的时候,使用各自的规范即可。

几个可供参考的规范和相关链接:

JS:

https://github.com/standard/standard

https://github.com/rwaldron/idiomatic.js/

https://github.com/airbnb/javascript

HTML & CSS:

http://codeguide.co

https://github.com/necolas/idiomatic-css

https://stylelint.io

永远不要为IDE编码

意思很简单,不同的IDE有不同的设定,你应该选择通用的设置,而不是完全顺从你选择的IDE工具。如果别人用不同的工具,就容易出麻烦了。比较好的理念,还是“约定大于配置”,使用大家约定俗成的规定是最方便的。

Two Scoops of Django - Django最佳实践指南01 - 导论