转载

python项目编码规范

笔者加入新公司几个月了，因为之前实习和工作的经历都是做新项目，对于维护老项目和阅读旧代码也没太多经验，踩了一些坑。笔者在还没有彻底了解业务的情况下就重构代码，导致延误了项目进度。so naive啊。。。。。。

最近感受最深的就是项目规范化很重要，尤其是多人协作的时候。人多了的时候，不同人的水平和代码风格差异很大，如果没有统一的规范，不同的人写的代码太个人化，有时候还有很多坏味道，导致协作和他人上手很困难，项目进度也会受到影响。

另外就是程序员需要的技能还是很多的，除了写代码实现需求，还需要能够很好地理解业务，和PM，测试，其他开发人员的沟通也很重要。

最近吃到的一些教训：

打断点单步执行是理解代码的一种比较好的方式。
项目规范化。一定要制定自己公司的代码规范，避免代码腐化，导致以后维护和修改成本巨大。
不要一上来就重构你觉得不好的东西，没有单元测试的代码重构起来风险极大，很有可能得不偿失。把你的想法和规范用到新的代码中，旧的代码涉及到的时候再尝试慢慢修改其中不好的地方。
注释和文档化很重要，降低别人理解和上手你的代码的难度。代码除了实现需求外，最重要的就是理解和维护。
对于不太明白怎么做的地方（比如docstring怎么写），看看知名的开源项目人家是怎么做的。

大概想了一下目前需要实施的规范：

工具

机器性能好的话强烈推荐pycharm，非常多实用功能。
请在你的IDE或者编辑器里找到pep8和pylint检测插件，务必打开。pylint能帮你消除很多代码坏味道。
使用的开发工具应该具有代码高亮，批量注释，pep8检测，pylint检测，自动生成docstring等功能。
vim请使用python-mode插件，集成了众多实用python插件。

编码风格

请遵循pep8标准，行长度可以适当放宽，但请不要超过120列，请使用格式优美的分行方式。

google的代码风格也可以参考。

《PEP 8 – Style Guide for Python Code》

Google开源项目风格指南-Python风格指南》

命名规范

按照pep8规则命名
注意函数动词和变量名词词性的区分
因为python没有类型声明，可以适当加上后缀比如url_list, info_dict等作为区分

函数

保持精简，注意复用，一次只做一件事。当需求变更时候，颗粒度细的代码更容易更改和适应变更。
注意函数的副作用，python的可变和非可变类型作为参数传入。
Think about future, design with flexibility, but only implement for production. 不要过度和超前设计，不要预测未来，仅需保持精简以便适应将来需求变更。
代码的写法应当使别人理解它所需的时间最小化
注意逻辑分块

docstring书写

对于复杂函数应该有良好的docstring注释，现统一使用sphinx格式的docstring，pycharm默认支持，vim请使用 heavenshell/vim-pydocstring 插件，其他编辑器请自行搜索安装。

以下是示例：

函数的精确描述，如果名称可以自解释可以省略。应当声明函数的意图和使用注意事项。虽然有时候一行行阅读代码也可以看懂，但是很多时候并不想看代码而是想立马知道该函数的功能。
需要说明的参数含义和类型，对于动态语言，不能自解释的参数类型应予以说明，并且复杂的传入参数比如嵌套字典应该有相应的示例。
返回值的含义和类型。复杂返回值应该有示例说明。
非开源项目并且无老外参与可以使用中文，某些英文注释理解困难。

def add_pdr(process, userid, log):
    """ Create and perform the target account operation PDR

    If the function/method is complex, I'd put a short one-line
    summary in the first line above, and a more detailed explanation
    here.

    :param dict process: dict of process details
    :param str userid: userid to perform actions on
    :param obj log: log object to perform logging to

    :raises KeyError: if the userid doesn't exist
    :raises APIError: if process dict is invalid

    :return: True on success, False upon failure

    """