第一章 项目开发流程

1.1 项目开发流程图

第二章 项目开发规范

2.1 可视化设计规范

2.1.1 布局设计

1. 画布中组件布局尽量清晰整齐，组件之间的连线避免交叉

2. 避免连线与组件位置重叠                         

3. 画布中的组件尽量不超过 50 个

4. 如果一行的组件过长，建议放到下一行，一行中的组件个数在 5-6 个左右

5. 8.0 版本中有个 "序列" 功能，可以更加增强美观度，建议使用

2.1.2 流程设计

1. Main 流程是自动化程序运行的唯一入口，建议其中只调用子流程，不放置其他组件

2. 一个流程在代码中其实对应项目类中的一个函数，因此子流程的功能不宜过多

3. 组件为设置变量、代码块、全局函数等无法直接判断其功能的时候，在组件上方输入注释，明确组件的功能（注释中不能含有英文格式的单引号，否则会报错）

2.1.3 命名

1. 所有命名均只包含字母、数字和下划线，并且不能以数字开头

2. 项目命名：大驼峰式命名（由一个或多个单词连接在一起，每一个单词的首字母都采用大写字母）

3. 子流程命名：全部小写，如有多个单词，使用下划线隔开                                

4. 变量命名：全部小写，如有多个单词，使用下划线隔开                              

5. 常量命名：全部大写，如有多个单词，使用下划线隔开

MAX_CLIENT = 100
MAX_CONNECTION = 1000
CONNECTION_TIMEOUT = 600

2.2 函数编码规范

2.2.1 代码块

1. 代码块组件中只适合写一些简单的代码，复杂的代码使用全局函数实现，否则不便于管理

2. 不要在代码块中定义函数，不管是否涉及传参

2.2.2 全局函数

1. 首先明确全局函数的工作原理：[http://support.i-search.com.cn/article/1543371220221

2. 全局函数中可以定义类，或者只定义函数，但是应尽量避免在类以及函数体以外的代码

2.2.3 代码格式

2.2.3.1 缩进

- 统一使用四个空格，不使用 tab 键。尽管设计器中的代码编辑器能自动将 tab 替换为四个空格，但是直接拷贝代码到其他编辑器中运行可能会出问题，而且也影响代码美观

2.2.3.2 行宽

- 每行代码尽量不超过 80 个字符 (在特殊情况下可以略微超过 80 ，但最长不得超过 120)

2.2.3.3 引号

- 标识单个字符串的引号如无特殊情况一律使用单引号 ‘…’

- 文档字符串使用三个双引号 “““……”””

- 原始字符串使用双引号 r"…"

2.2.3.4 空行

- 模块级函数和类定义之间空两行

- 类成员函数之间空一行

 class A(object):

       def __init__(self):
           pass

       def a(self):
           pass


 def b():
       pass

2.2.3.5 import 语句

- 分行书写

# 正确的写法
import os
import sys

# 不推荐这么写
import os,sys

- import 语句应该放在文件头部，置于模块说明及文档字符串之后，于全局变量之前

- 尽量使用命名空间，防止发生命名冲突  

# 正确的写法
import bar
import foo.bar
bar.Bar()
foo.bar.Bar()

# 不推荐的写法
from bar import *
from foo.bar import *  

2.2.3.6 空格

- 在二元运算符两边各空一格 [=, -, +=, ==, >, in, is, not, and]

# 正确的写法
i = i + 1
submitted += 1
x = x * 2 - 1
hypot2 = x * x + y * y
c = (a + b) * (a - b)
 
# 不推荐的写法
i=i+1
submitted+=1
x=x*2-1
hypot2=x*x+y*y
c=(a+b)*(a-b)

- 函数的参数列表中逗号之后要有空格

# 正确的写法
def complex(real, imag):
    pass

# 不推荐的写法
def complex(real,imag):
    pass

- 函数的参数列表中，默认值等号两边不要添加空格

# 正确的写法
def complex(real, imag=0.0):
    pass

# 不推荐的写法
def complex(real, imag = 0.0):
    pass

2.2.3.7 换行

- Python 支持括号内的换行，若左括号后还有文本，则第二行缩进到括号的起始处

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)

- 可以使用反斜杠换行，二元运算符等应出现在行末。同时长字符串也可以用此方法换行

session.query(MyTable).\
    filter_by(id=1).\
    one()

print 'Hello, '\
    '%s %s!' %\
    ('Harry', 'Potter')

- 一行只允许写一个语句

# 正确的写法
do_first()
do_second()
do_third()

# 不推荐的写法
do_first();do_second();do_third()

- if/for/while 一定要换行

# 正确的写法
if foo == 'blah':
    do_blah_thing()

# 不推荐的写法
if foo == 'blah': do_blash_thing()

2.2.4 注释

2.2.4.1 行注释

- 至少使用两个空格和语句分开，“#”号后面加一个空格然后写注释内容

x = x + 1   # x自增1

2.2.4.2 块注释

- “#”号后空一格，段落件用空行分开（同样需要“#”号）

# 块注释
# 块注释
# 块注释
# 块注释
# 块注释

2.2.4.3 文档字符串

- 作为文档的文档字符串一般出现在模块头部、函数和类的头部，这样在 python 中可以获取到它。编辑器和 IDE 也可以根据文档字符串给出自动提示

- 文档注释以三个双引号开头和结尾, 首行不换行, 如有多行, 末行需换行, 以下是 Google 的 docstring 风格示例     

# -*- coding: utf-8 -*-
"""Example docstrings.
This module demonstrates documentation as specified by the `Google Python
Style Guide`_. Docstrings may extend over multiple lines. Sections are created
with a section header and a colon followed by a block of indented text.
Example:
    Examples can be given using either the ``Example`` or ``Examples``
    sections. Sections support any reStructuredText formatting, including
    literal blocks::
        $ python example_google.py
Section breaks are created by resuming unindented text. Section breaks
are also implicitly created anytime a new section starts.
"""

2.3 可移植性规范

2.3.1 相对路径

- 流程中需要读取 Excel、图片、json 等文件时，从可移植性的角度考虑，一律使用相对路径:[http://support.i-search.com.cn/article/1543905442833

import os

os.path.dirname(__file__)

2.3.2 导入自建库

- 需要导入自己写的库时，同样使用相对路径的方法，将.py 脚本保存在当前项目的 data 文件夹下，然后通过代码将那个文件夹加入环境变量

import sys
import os

sys.path.append(os.path.dirname(__file__) + '/scripts')  # scripts为存放自建库的文件夹

2.4 机器人部署规范

2.4.1 冲突预防

1. 同一台机器部署了多个机器人时，相互之间的运行时间要保证能错开

2. 设计流程时需要考虑机器人运行前以及运行完成之后的运行环境，保证运行完毕之后不影响其他机器人的运行。举个例子，某台机器部署了两个机器人，都需要对 sap 系统进行操作，其中一个机器人运行完毕以后没有退出 sap 系统，另一个机器人之后运行时如果没有先检测并关闭 sap 系统，就会受到前一个机器人的影响导致无法正常运行

2.4.2 合理利用

- 综合考虑各机器人运行平台，将机器人合理部署至平台，避免出现某些机器闲置而另外一些机器忙不过来的情况

2.4.3 写清备注

- 机器人部署时写明开发人员的名字、功能、预计运行时长等基本信息

2.4.4 避免繁复

- 同一个机器人如果要求只在某些天数不运行，避免部署很多个相同的机器人然后设置不同的时间规则。举个例子，扬州直批清账需求要求如下                                 

一年中有 38 天不运行，其余每天都运行，那么可以在流程中建一个变量存储所有需要排除的日期，在流程运行时先判断当前日期是否在那个变量中，如果是，则流程停止运行，否则正常运行流程。这样部署的时候只需部署一次，将运行时间设置为每天凌晨 2 点即可

第三章 项目开发技巧

3.1 快速调试

- 遇到需要验证自己想法的时候，可以直接打开 python 编译器输入代码，共有三种方式：

（1）D:\iS-RPA\plugin\Com.Isearch.Func.Python\python.exe

（2）D:\iS-RPA\plugin\Com.Isearch.Func.Python\Lib\site-packages\pythonwin\Pythonwin.exe

（3）D:\iS-RPA\plugin\Com.Isearch.Func.Python\idle.bat

建议选择其中一种并将其快捷方式添加到桌面

3.2 灵活使用 help()与 dir()

- dir()函数不带参数时，返回当前范围内的变量、方法和定义的类型列表；带参数时，返回参数的属性、方法列表。如果参数包含方法 __dir__()，该方法将被调用。如果参数不包含 __dir__()，该方法将最大限度地收集参数信息

- help() 函数用于查看函数或模块用途的详细说明                                      

3.3 不要轻信延时

- 同一流程位置可能因网络、电脑卡顿、从本机部署至云服务器等原因导致运行时间不一样

- 关键位置使用获取文本、是否激活窗口等组件来代替前置后置延时，保证流程的稳定性

3.4 警惕图片检测

- 图片检测一般用于判断是否到达了某个预期的页面，原理是对屏幕中某一块像素区域进行截图并调用 opencv 中的图像识别算法，这种方式会极大地拖慢流程的运行，如果可以，尽量用获取文本，是否激活窗口等组件来代替图片检测

3.5 论坛是个好东西

- 遇到搞不定的问题优先查看论坛，可能已经有人碰到过类似的问题并给出了解决方案

- 论坛地址：http://support.i-search.com.cn/

- 技术分享常见问题汇总贴：[http://support.i-search.com.cn/article/1540084292275

第四章 进阶提升指南

4.1 阅读源码

- 不论是艺赛旗的源码还是网上常用第三方库的源码，有空的时候都应该去读一读，通过阅读优秀的源码不仅能让阅读者理清思路，而且可以逐渐提高阅读者的编程水平

- 在充分理解源码的基础上，我们还可以根据自己的实际开发需要改写源码，参考：[http://support.i-search.com.cn/article/1542620701678

4.2 阅读官方文档

- 想要完全了解某个库的用法，最好的办法还是去阅读这个库的官方文档。一般来说，正规的库总能找到相应的官方文档（大多数时候没有中文版），网上查找的博客教程通常只会涉及一小部分的用法，官方文档中则包含了全部用法

4.3 学好英语

- 虽然国外很多优秀的书籍、技术文档等都有对应的中文翻译版，但是也存在大量全英文版的资料。在 Stack Overflow 等社区搜索 solution 以及交流时都不可避免地会大量用到英语，因此想要进阶提升，学好英语很关键

第五章 后记

鄙人才疏学浅，自己编写的开发规范难免有疏漏，欢迎大家指正与补充。另外，规范的实施是一件需要付出时间与实践的事情，路漫漫其修远兮，希望大家都能设计优美的流程，写出强大的代码，搞定变态的需求！ ——杨雷