Python

LincZero大约 3 分钟

Python

编写习惯

注释类

文档字符串（类似JavaDoc的文档注释）

格式
- 第一行应该是关于对象用途的简介。简短起见，不用明确的陈述对象名或类型（Java则需要）。这一行应该以大写字母开头，以句号结尾
- 第二行应该空出来，与接下来的详细描述明确分隔
- 接下来的文档应该有一或多段描述对象的调用约定、边界效应等
- 第一行之后的第一个非空行决定了整个文档的缩进格式（我们不用第一行是因为它通常紧靠着起始的引号，缩进格式显示的不清楚。）
作用
- 可以调用函数的__doc__属性查看

demo

  >>> def my_function():
  ...     """Do nothing, but document it.
  ...
  ...     No, really, it doesn't do anything.
  ...     """
  ...     pass
  ...
  >>> print(my_function.__doc__)
  Do nothing, but document it.
  
      No, really, it doesn't do anything.

函数注解（参数和返回值的注释）

概念
- 函数注解open in new window 是关于用户自定义的函数的完全可选的、随意的元数据信息。无论 Python 本身或者标准库中都没有使用函数注解；本节只是描述了语法。第三方的项目是自由地为文档，类型检查，以及其它用途选择函数注解。
- 注解是以字典形式存储在函数的 __annotations__ 属性中，对函数的其它部分没有任何影响
格式
- 参数注解（Parameter annotations）是定义在参数名称的冒号后面，紧随着一个用来表示注解的值得表达式
- 返回注释（Return annotations）是定义在一个 -> 后面，紧随着一个表达式，在冒号与 -> 之间。下面的示例包含一个位置参数，一个关键字参数，和没有意义的返回值注释
作用
- 可以调用__annotations__（注释文）查看

demo

  >>> def f(ham: 42, eggs: int = 'spam') -> "Nothing to see here":
  ...     print("Annotations:", f.__annotations__)
  ...     print("Arguments:", ham, eggs)
  ...
  >>> f('wonderful')
  Annotations: {'eggs': <class 'int'>, 'return': 'Nothing to see here', 'ham': 42}
  Arguments: wonderful spam

TODO注释

# @TODO: Fix ME!!! 不用@符号也行

注释的样式和有所不同，会高亮

PyCharm中，左下角TODO或双Shift搜索TODO，可以弹出TODO界面，查看所有有TODO注释的代码

# 考虑个人常用的符号
# @TODO: fixing bug
# @Question
# @Attention
	# @noexcept
    # @except
    # @Fixed Bug
    # @Fixing Bug
# @NOTE

"""
:except
"""

编码风格

对于 Python，PEP 8open in new window 引入了大多数项目遵循的风格指导。它给出了一个高度可读，视觉友好的编码风格

每个 Python 开发者都应该读一下，大多数要点都会对你有帮助：

使用 4 空格缩进，而非 TAB
在小缩进（可以嵌套更深）和大缩进（更易读）之间，4空格是一个很好的折中。TAB 引发了一些混乱，最好弃用
折行以确保其不会超过 79 个字符
这有助于小显示器用户阅读，也可以让大显示器能并排显示几个代码文件
使用空行分隔函数和类，以及函数中的大块代码
可能的话，注释独占一行
使用文档字符串
把空格放到操作符两边，以及逗号后面，但是括号里侧不加空格：a = f(1, 2) + g(3, 4)
统一函数和类命名
推荐类名用 大驼峰命名，函数和方法名用 小写_和_下划线。总是用 self 作为方法的第一个参数（关于类和方法的知识详见初识类open in new window ）
不要使用花哨的编码，如果你的代码的目的是要在国际化环境。Python 的默认情况下，UTF-8，甚至普通的 ASCII 总是工作的最好
同样，也不要使用非 ASCII 字符的标识符，除非是不同语种的会阅读或者维护代码。

Python

Python

目录

编写习惯

注释类

文档字符串（类似JavaDoc的文档注释）

函数注解（参数和返回值的注释）

TODO注释

编码风格

编码习惯