Python代码规范
<ul>
<li><font color="blue"><strong>更新日期：2021-5-11</strong></font>
<br/></li>
</ul>
<h2>注释</h2>
<h4><strong>1.单行函数注释</strong></h4>
<ul>
<li>示例</li>
</ul>
<pre><code class="language-python"># 【fish】获取原始数据模板列表 -2021/3/29
def get_tmpls(query, status):
# 获取符合条件模板信息
tmpls_info = self._tmpl.get_tmpls_data()
if not tmpls_info:
# 没有模板信息,返回错误
return _SERVERS_ERR["NO_TMPLS_DATA"]
pass</code></pre>
<ul>
<li>说明
<ul>
<li>该注释仅适用于对简单函数或方法进行说明，格式："<strong>【开发者】函数说明 -最近更新日期</strong>"
<br/></li>
</ul></li>
</ul>
<h4><strong>2.多行函数注释</strong></h4>
<ul>
<li>示例</li>
</ul>
<pre><code class="language-python">"""
【fish】获取原始数据模板列表 -2021/3/29
- 获取前需先设置模板ID
@Params
:query:dict: 查询条件
- tmpl_name:str: 需要查询的模板名称
:status:int: 模板启用状态
@Return
:list<TemplateModel>: 返回模板对象列表
@Errors:
- ValueError: 参数校验错误
- TypeError: 参数类型错误
"""
def get_tmpls(query, status):
# 获取符合条件模板信息
tmpls_info = self._tmpl.get_tmpls_data()
if not tmpls_info:
# 没有模板信息,返回错误
return _SERVERS_ERR["NO_TMPLS_DATA"]
pass</code></pre>
<ul>
<li>说明
<ul>
<li>首行注释：对函数或方法进行简要说明，格式："<strong>【开发者】函数说明 -最近更新日期</strong>"</li>
<li>次行注释：可对首行注释进一步进行说明，允许多行，但每行注释前需使用："<strong>-</strong>" 符号进行标识</li>
<li>参数注释：开头统一使用"<strong>@Params</strong>"进行标识，具体参数说明切换至下一行开始并进一步缩进，具体参数说明的格式："<strong>:参数名:参数类型: 参数说明</strong>"；同时，对于单个参数，还可以对其内部子参数进一步说明，需换至下一行开始并进一步缩进，说明格式："<strong>- 子参数名:子参数类型: 子参数说明</strong>"</li>
<li>返回值注释：开头统一使用"<strong>@Return</strong>"进行标识，具体返回值说明切换至下一行开始并进一步缩进，具体说明格式："<strong>:返回值类型: 返回值说明</strong>"</li>
<li>错误异常注释：开头统一使用"<strong>@Errors</strong>"进行标识，具体错误异常说明切换至下一行开始并进一步缩进，具体说明格式："<strong>- 错误异常类型: 错误异常说明</strong>"
<br/></li>
</ul></li>
</ul>
<h4><strong>3.单行类注释</strong></h4>
<ul>
<li>示例</li>
</ul>
<pre><code class="language-python"># 【fish】原始数据类 -2021/3/29
class RawData:
def __init__(self):
pass</code></pre>
<ul>
<li>说明
<ul>
<li>该注释仅适用于对简单类进行说明，格式："<strong>【开发者】类名 -该类创建日期</strong>"
<br/></li>
</ul></li>
</ul>
<h4><strong>4.多行类注释</strong></h4>
<ul>
<li>示例</li>
</ul>
<pre><code class="language-python">class RawData:
"""
【fish】原始数据类 -2021/3/29
- 用于对原始数据模块校验的处理
- 原始数据基本属性的封装
"""
def __init__(self):
pass</code></pre>
<ul>
<li>说明
<ul>
<li>首行注释：固定介绍，格式："<strong>【开发者】类名 -该类创建日期</strong>"</li>
<li>次行注释：可对类进一步进行说明，允许多行，但每行注释前需使用："<strong>-</strong>" 符号进行标识
<br/></li>
</ul></li>
</ul>
<h2>空行</h2>
<h4><strong>1.函数之间预留行数</strong></h4>
<ul>
<li>示例</li>
</ul>
<pre><code class="language-python">def get_rdata():
pass
def get_tmpls():
pass
class RawData:
def get(self):
pass
def set(self):
pass</code></pre>
<ul>
<li>说明
<ul>
<li>统一预留一行
<br/></li>
</ul></li>
</ul>
<h4><strong>2.类之间预留行数</strong></h4>
<ul>
<li>示例</li>
</ul>
<pre><code class="language-python">class RawData:
pass
class Tmpl:
pass</code></pre>
<ul>
<li>说明
<ul>
<li>统一预留两行
<br/></li>
</ul></li>
</ul>
<h2>命名风格</h2>
<h4><strong>1.类命名</strong></h4>
<p><img src="https://www.showdoc.com.cn/server/api/attachment/visitfile/sign/244a3abfcc8f3d54bdc88a951a0fcea6" alt="" /></p>
<p><br/></p>
<h4><strong>2.方法名、参数名、成员变量、局部变量命名</strong></h4>
<ul>
<li>示例</li>
</ul>
<pre><code class="language-python">local_value = 1
def get_http_msg(var_name):
inner_var = var_name</code></pre>
<ul>
<li>说明
<ul>
<li>统一使用PYTHON标准命名方式
<br/></li>
</ul></li>
</ul>
<h4><strong>3.常量命名</strong></h4>
<p><img src="https://www.showdoc.com.cn/server/api/attachment/visitfile/sign/46be889a589aeb8131430beff370a8ee" alt="" /></p>
<p><br/></p>
<h4><strong>4.包命名</strong></h4>
<ul>
<li>示例</li>
</ul>
<pre><code class="language-python">from service.stl.raw_data import RawDataTemplate</code></pre>
<ul>
<li>说明
<ul>
<li>包名统一使用小写，点分隔符之间尽量保证仅有一个自然语义的英语单词</li>
<li>包名统一使用单数形式，但是类名如果有复数含义，类名可以使用复数形式
<br/></li>
</ul></li>
</ul>
<h4><strong>5.单词缩写</strong></h4>
<ul>
<li>示例</li>
</ul>
<pre><code class="language-python">"""6个字母以下不简写"""
# eg:raw --> raw
"""7-12个字母以下缩写至不超过6个单词"""
# eg:template --> tmpl
# eg:information --> info</code></pre>
<ul>
<li>说明
<ul>
<li>英语单词缩写需要符合基本的英文规范</li>
<li>若项目定义了“接口文档或数据字典命名规范”，缩写需与该规范保持一致</li>
<li>杜绝完全不规范的缩写，避免望文不知义
<br/></li>
</ul></li>
</ul>
<h4><strong>6.枚举类</strong></h4>
<ul>
<li>示例</li>
</ul>
<pre><code class="language-python">from enum import Enum
class AccountEnum(Enum):
ALIPAY = 1
CREDIT_CARD = 2</code></pre>
<ul>
<li>说明
<ul>
<li>枚举类名带上 Enum 后缀</li>
<li>枚举成员名称需要全大写，单词间用下划线隔开
<br/></li>
</ul></li>
</ul>
<h4><strong>7.各层命名规约</strong></h4>
<p><img src="https://www.showdoc.com.cn/server/api/attachment/visitfile/sign/19cb93d785a41526fcd9c3236e68e1fe" alt="" />
<img src="https://www.showdoc.com.cn/server/api/attachment/visitfile/sign/fe12058dc7f7c7519a6dadcabd24a3f5" alt="" /></p>
<p><br/></p>
<h4><strong>8.其他规则</strong></h4>
<ul>
<li>示例</li>
</ul>
<pre><code class="language-python"># eg: 常量与变量的命名
start_time, work_queue, name_list, TERMINATED_THREAD_COUNT = None, None, None, None
# eg: 设计模式
class OrderFactory:
pass</code></pre>
<ul>
<li>说明
<ol>
<li>在常量与变量的命名时，表示类型的名词放在词尾，以提升辨识度</li>
<li>如果模块、接口、类、方法使用了设计模式，在命名时需体现出具体模式
<br/></li>
</ol></li>
</ul>
<h2>函数</h2>
<h4><strong>1.函数命名</strong></h4>
<ul>
<li>示例</li>
</ul>
<pre><code class="language-python">def get_tmpls():
pass
def get_tmpl_by_id():
pass</code></pre>
<ul>
<li>说明
<ul>
<li>基本格式："<strong>动词 + 名词 + 修饰或条件</strong>"</li>
<li>上面格式中的："<strong>动词 + 名词</strong>" 为必须组成部分，"<strong>修饰或条件</strong>" 为可选部分
<br/></li>
</ul></li>
</ul>
<h4><strong>2.函数有效行数</strong></h4>
<ul>
<li>说明
<ul>
<li>建议单个简单函数体或方法体内有效代码行数不超过20行</li>
<li>建议单个复杂函数体或方法体内有效代码行数不超过40行</li>
<li>非强制要求
<br/></li>
</ul></li>
</ul>
<h2>应用分层</h2>
<h4><strong>1.分层说明</strong></h4>
<p><img src="https://www.showdoc.com.cn/server/api/attachment/visitfile/sign/532850c862dadfb31fb930b4eef0e438" alt="" />
<img src="https://www.showdoc.com.cn/server/api/attachment/visitfile/sign/645ea8bab9037c6b6b142702b82cd736" alt="" /></p>
<p><br/></p>
<h4><strong>2.分层异常处理规约</strong></h4>
<p><img src="https://www.showdoc.com.cn/server/api/attachment/visitfile/sign/b8f63b3efe4e9aca1cc9541351e5a08a" alt="" />
<img src="https://www.showdoc.com.cn/server/api/attachment/visitfile/sign/0c2147a232f873523f27eacf49784c26" alt="" /></p>
<p><br/></p>
<h4><strong>3.分层领域模型规约</strong></h4>
<p><img src="https://www.showdoc.com.cn/server/api/attachment/visitfile/sign/dd553e4fe9dbb7604fe5c47958d6a031" alt="" /></p>
<p><br/></p>
<h2>设计规约</h2>
<ol>
<li>
<p>【强制】存储方案和底层数据结构的设计获得评审一致通过，并沉淀成为文档。
说明：有缺陷的底层数据结构容易导致系统风险上升，可扩展性下降，重构成本也会因历史数据迁移和系
统平滑过渡而陡然增加，所以，存储方案和数据结构需要认真地进行设计和评审，生产环境提交执行后，
需要进行 double check。
正例：评审内容包括存储介质选型、表结构设计能否满足技术方案、存取性能和存储空间能否满足业务发
展、表或字段之间的辩证关系、字段名称、字段类型、索引等；数据结构变更（如在原有表中新增字段）
也需要进行评审通过后上线</p>
</li>
<li>
<p>【强制】在需求分析阶段，如果与系统交互的 User 超过一类并且相关的 User Case 超过 5 个，使用用例图来表达更加清晰的结构化需求。</p>
</li>
<li>
<p>【强制】如果某个业务对象的状态超过 3 个，使用状态图来表达并且明确状态变化的各个触发条件。
说明：状态图的核心是对象状态，首先明确对象有多少种状态，然后明确两两状态之间是否存在直接转换
关系，再明确触发状态转换的条件是什么。
正例：淘宝订单状态有已下单、待付款、已付款、待发货、已发货、已收货等。比如已下单与已收货这两
种状态之间是不可能有直接转换关系的。</p>
</li>
<li>
<p>【强制】如果系统中某个功能的调用链路上的涉及对象超过 3 个，使用时序图来表达并且明确各调用环节的输入与输出。
说明：时序图反映了一系列对象间的交互与协作关系，清晰立体地反映系统的调用纵深链路。</p>
</li>
<li>
<p>【强制】如果系统中模型类超过 5 个，并且存在复杂的依赖关系，使用类图来表达并且明确类之间的关系。
说明：类图像建筑领域的施工图，如果搭平房，可能不需要，但如果建造蚂蚁 Z 空间大楼，肯定需要详细
的施工图。</p>
</li>
<li>
<p>【强制】如果系统中超过 2 个对象之间存在协作关系，并且需要表示复杂的处理流程，使用活动图来表示。
说明：活动图是流程图的扩展，增加了能够体现协作关系的对象泳道，支持表示并发等。</p>
</li>
<li>【推荐】系统架构设计时明确以下目标：
⚫ 确定系统边界。确定系统在技术层面上的做与不做。
⚫ 确定系统内模块之间的关系。确定模块之间的依赖关系及模块的宏观输入与输出。
⚫ 确定指导后续设计与演化的原则。使后续的子系统或模块设计在一个既定的框架内和技术方向上继续演化。
⚫ 确定非功能性需求。非功能性需求是指安全性、可用性、可扩展性等。</li>
</ol>