logseq-1/pages/google python风格指南.md

• Python风格规范 — Google 开源项目风格指南 (zh-google-styleguide.readthedocs.io)
• 分号
  • #+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，在程序的主文件开头添加#!/usr/bin/env python3(以支持virtualenv)或者#!/usr/bin/python3 #+END_TIP
• 注释和文档字符串(docstring)
  • #+BEGIN_TIP 模块、函数、方法的文档字符串和内部注释一定要采用正确的格式 #+END_TIP
• 标点符号、拼写和语法
  • #+BEGIN_TIP 注意标点符号、拼写和语法。文笔好的注释比差的注释更容易理解 #+END_TIP
• 字符串
  • #+BEGIN_TIP 应该用f-string、%或format方法来格式化字符串。即使所有参数都是字符串，也如此。你可以自行评判合适的选项。可以使用+ 单词拼接，但是不要使用+实现格式化 #+END_TIP
• 文件、套接字 (socket) 和类似的有状态资源
  • #+BEGIN_TIP 使用完文件和套接字以后，显式地关闭它们。自然地，这条法则也应该扩展到其他在内部使用套接字的可关闭资源(比如数据库连接)和其他需要用类似方法关停的资源。其他例子[mmap] (https://docs.python.org/zh-cn/3/library/mmap.html)映射、h5py 的文件对象和matplotlib.pyplot 的图像窗口 #+END_TIP
• TODO (待办) 注释
  • #+BEGIN_TIP 在临时、短期和不够完美的代码上添加TODO(待办)注释 #+END_TIP
• 导入 (import) 语句的格式
  • #+BEGIN_TIP 导入语句应该各自独占一行。typing和collections.abc的导入除外 #+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) logseq.order-list-type:: number
    • 仅在有额外类型信息是才需要注解方法中self或cls的类型。例如： logseq.order-list-type:: number

      • @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