python代码注释只有一种_Python代码注释

第一点：为了避免麻烦，在文件的开头加上这两句。

#!/usr/bin/env python

# -*- coding: utf-8 -*

第二点：每一个Python文件的开头，紧接着第一点所说的两行代码之后，我们往往要写上关于这个模块即这个Python文件实现的功能一些注意点，可能会发生的错误，总之你得注释要让使用它的人很明白你得代码段，比如：

"""

requests.cookies

~~~~~~~~~~~~~~~~

Compatibility code to be able to use `cookielib.CookieJar` with requests.

requests.utils imports from here, so be careful with imports.

"""

或者

"""

This is the Scrapy engine which controls the Scheduler, Downloader and Spiders.

For more information see docs/topics/architecture.rst

"""

可能，你不看代码，都已经知道接下来的是什么了，那么你能找到上面这个注释是出自哪个文件吗？

第三点：每一个类下面加上关于这个类的说明以及用法，这样使用它的人可能都不要知道他的内部构造，就可以使用他了，我们看看这个。

第一：这个类是干嘛的？

第二：经常在什么情况下使用？

第三：如何使用？

都交待说明的很详细，你不看代码估计已经会使用了。

class HTTPAdapter(BaseAdapter):

"""The built-in HTTP Adapter for urllib3.

Provides a general-case interface for Requests sessions to contact HTTP and

HTTPS urls by implementing the Transport Adapter interface. This class will

usually be created by the :class:`Session ` class under the

covers.

:param pool_connections: The number of urllib3 connection pools to cache.

:param pool_maxsize: The maximum number of connections to save in the pool.

:param max_retries: The maximum number of retries each connection

should attempt. Note, this applies only to failed DNS lookups, socket

connections and connection timeouts, never to requests where data has

made it to the server. By default, Requests does not retry failed

connections. If you need granular control over the conditions under

which we retry a request, import urllib3's ``Retry`` class and pass

that instead.

:param pool_block: Whether the connection pool should block for connections.

Usage::

>>> import requests

>>> s = requests.Session()

>>> a = requests.adapters.HTTPAdapter(max_retries=3)

>>> s.mount('http://', a)

"""

第四点：每一个函数下面务必加上多行注释，很有可能你的函数注释只有一行，或者两行，你可以使用单行注释，也可以使用多行注释，这里与类函数说明相当，注释中往往包含使用说明，注意点。

def __setstate__(self, state):

# Can't handle by adding 'proxy_manager' to self.__attrs__ because

# self.poolmanager uses a lambda function, which isn't pickleable.

或者

def has_capacity(self):

"""Does the engine have capacity to handle more spiders"""

return not bool(self.slot)

第五点：在必要的地方加上单行注释。这些地方不外乎

1、你不怎么理解的代码

2、别人可能不理解的代码

3、提醒自己或者别人注意的代码、重要代码

self.inprogress = set() # requests in progress

assert not self.running, "Engine already running"

以上，更多的编码习惯。可以去读一读request的代码。