96 lines
5.1 KiB
Markdown
Executable File
96 lines
5.1 KiB
Markdown
Executable File
- [Python风格规范 — Google 开源项目风格指南 (zh-google-styleguide.readthedocs.io)](https://zh-google-styleguide.readthedocs.io/en/latest/google-python-styleguide/python_style_rules/)
|
||
- **分号**
|
||
- #+BEGIN_TIP
|
||
不要在行尾加分号，也不要用分号将两条语句合并到一行
|
||
#+END_TIP
|
||
- **行宽**
|
||
- #+BEGIN_TIP
|
||
最大行宽是80个字符
|
||
#+END_TIP
|
||
- **括号**
|
||
- #+BEGIN_TIP
|
||
使用括号时宁缺毋滥
|
||
#+END_TIP
|
||
- **缩进**
|
||
- #+BEGIN_TIP
|
||
用四个空格作为缩进
|
||
#+END_TIP
|
||
- **序列的尾部要添加逗号吗？**
|
||
- #+BEGIN_TIP
|
||
仅当`]`，`)`，`}`和最后一个元素不在同一行时，推荐在序列尾部添加逗号，我们的Python自动格式化工具会把尾部的逗号视为一种格式提示
|
||
#+END_TIP
|
||
- **Shebang行**
|
||
- #+BEGIN_TIP
|
||
大部分`.py`文件不必以`#!`开始。可以根据[PEP-394](http://www.python.org/dev/peps/pep-0394/)，在程序的主文件开头添加`#!/usr/bin/env python3`(以支持virtualenv)或者`#!/usr/bin/python3`
|
||
#+END_TIP
|
||
- **注释和文档字符串(docstring)**
|
||
- #+BEGIN_TIP
|
||
模块、函数、方法的文档字符串和内部注释一定要采用正确的格式
|
||
#+END_TIP
|
||
- **标点符号、拼写和语法**
|
||
- #+BEGIN_TIP
|
||
注意标点符号、拼写和语法。文笔好的注释比差的注释更容易理解
|
||
#+END_TIP
|
||
- **字符串**
|
||
- #+BEGIN_TIP
|
||
应该用[f-string](https://docs.python.org/zh-cn/3/reference/lexical_analysis.html#f-strings)、`%`或`format`方法来格式化字符串。即使所有参数都是字符串，也如此。你可以自行评判合适的选项。可以使用`+` 单词拼接，但是不要使用`+`实现格式化
|
||
#+END_TIP
|
||
- **文件、套接字 (socket) 和类似的有状态资源**
|
||
- #+BEGIN_TIP
|
||
使用完文件和套接字以后，显式地关闭它们。自然地，这条法则也应该扩展到其他在内部使用套接字的可关闭资源(比如数据库连接)和其他需要用类似方法关停的资源。其他例子[mmap] (https://docs.python.org/zh-cn/3/library/mmap.html)映射、[h5py 的文件对象](https://docs.h5py.org/en/stable/high/file.html)和[matplotlib.pyplot 的图像窗口](https://matplotlib.org/2.1.0/api/_as_gen/matplotlib.pyplot.close.html)
|
||
#+END_TIP
|
||
- **TODO (待办) 注释**
|
||
- #+BEGIN_TIP
|
||
在临时、短期和不够完美的代码上添加TODO(待办)注释
|
||
#+END_TIP
|
||
- **导入 (import) 语句的格式**
|
||
- #+BEGIN_TIP
|
||
导入语句应该各自独占一行。[typing和collections.abc的导入除外](https://zh-google-styleguide.readthedocs.io/en/latest/google-python-styleguide/python_style_rules/#typing-imports)
|
||
#+END_TIP
|
||
- **语句**
|
||
- #+BEGIN_TIP
|
||
通常每个语句应该独占一行
|
||
#+END_TIP
|
||
- **访问器 (getter) 和设置器 (setter)**
|
||
- #+BEGIN_TIP
|
||
在访问和设置变量值时，如果访问器和设置器(又名访问子accessor和变异子mutator)可以产生有意义的作用或效果，则可以使用
|
||
#+END_TIP
|
||
- **命名**
|
||
- #+BEGIN_TIP
|
||
模块名 : `module_name`; 包名 : `package_name`; 类名 : `ClassName`; 方法名 : `method_name`; 异常名 : `ExceptionName`; 函数名 : `function_name`, `query_proper_noun_for_thing`, `send_acronym_via_https`; 全局常量名 : `GLOBAL_CONSTANT_NAME` ; 全局变量名 : `global_var_name`; 实例名 : `instance_var_name`; 函数参数名 : `function_parameter_name`; 局部变量名 : `local_var_name`
|
||
#+END_TIP
|
||
- **主程序**
|
||
- #+BEGIN_TIP
|
||
使用Python时，提供给`pydoc`和单元测试的模块必须是可导入的。如果一个文件是可执行文件，该文件的主要功能应该位于`main()`函数中。你的代码必须在执行主程序前检查`if __name__ = '__main__'`，这样导入模块时不会执行主程序
|
||
#+END_TIP
|
||
- **函数长度**
|
||
- #+BEGIN_TIP
|
||
函数应该小巧而专一
|
||
#+END_TIP
|
||
- **类型注解 (type annotation)**
|
||
- 通用规则
|
||
- 熟读[PEP-484 (python.org)](https://www.python.org/dev/peps/pep-0484/)
|
||
logseq.order-list-type:: number
|
||
- 仅在有额外类型信息是才需要注解方法中`self`或`cls`的类型。例如：
|
||
logseq.order-list-type:: number
|
||
- ```python
|
||
@classmethod
|
||
def create(cls: Type[_T]) -> _T:
|
||
return cls()
|
||
```
|
||
- 类似地，不需要注解`__init__`的返回值(只能返回`None`)
|
||
logseq.order-list-type:: number
|
||
- 对于其他不需要限制变量类型或返回类型的情况，应该使用`Any`
|
||
logseq.order-list-type:: number
|
||
- 无需注解模块中所有函数
|
||
logseq.order-list-type:: number
|
||
- 至少需要注解你的公开API
|
||
logseq.order-list-type:: number
|
||
- 你可以自行权衡，一方面要保证代码的安全性与清晰性，另一方面要兼顾灵活性
|
||
logseq.order-list-type:: number
|
||
- 应该注解那些容易出现类型错误的代码(比如曾经出现过错误或疑难杂症)
|
||
logseq.order-list-type:: number
|
||
- 应该注解晦涩难懂的代码
|
||
logseq.order-list-type:: number
|
||
- 应该注解那些类型已经确定的代码.多数情况下，即使了解了成熟代码中所有函数，也不会丧失太多灵活性
|
||
logseq.order-list-type:: number |