注册用户享全站资源 并成为粉丝 不定时福利发放
 

Python里的一些注释规范

6
发表时间:2019-06-26 10:42

写代码注释是一件很重要的事情,如果你写的一段函数给别人调用那么往往都需要配上一些基本的注释。写好代码可以让别人容易阅读你的代码。试想一 下:如果你在github上面找到一段你想要的代码,这段代码有200行,可能这些代码我们要进行改造,那么这时候如果代码中都没有恰当的注释,我们可能 要用比较久的时间去通读一下他的代码。

相反,如果这些代码有一些恰当的注释,我们可能会更加好理解一点。学会注释是编码过程中不可或缺的一部分。那么什么样的注释才是规范的注释,才能让其他看你代码的人能快速的了解你得代码结构呢。我们今天就说一说 有关于Python的一些注释规范。

在说规范之前我们有必要先看以下Python的注释有哪些?

单行注释

多行注释

特殊注释

按照每一个注释进行简单的介绍(我们截选request库的一段文件):


Python里的一些注释规范0
第一行第二行:为上述所说的特殊注释,这两个注释也几乎是在你所编写的每一个py文件中应该存在的,正常情况下第一第二行通用格式。


关于 #!/usr/bin/env python

1、必须是文件的第一行

2、必须以#!开头

3、#!/usr/bin/env python告诉LINUX/UNIX去找到python的翻译器。

关于: # -*- coding: utf-8 -*-

1、基本上在文件的第二行,在#!/usr/bin/env python的下一行

2、python interpret如何解释字符串的编码

3、当你的文件中出现中文的时候,你必须使用它

第四到第十三行:为上述所说的所行注释。多行注释,以三个引号开始,三个引号结尾。这三个引号可以使单引号也可以是双引号。

1、一般类文档,函数文档,字符串之类的用双引号,变量用单引号。

第二十一行:我们所说的单行注释,单行注释以#开头标识。

你也可以连续多次使用#单行注释来代替多行注释,但是我们并不推荐那么做。

知道了上述的注释之后,我们需要知道的是在哪些场合使用哪些注释。

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

#!/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"""

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

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

第一:这个类是干嘛的?

第二:经常在什么情况下使用?

第三:如何使用?

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

classHTTPAdapter(BaseAdapter):"""The built-in HTTP Adapter for urllib3.Provides a general-case interface for Requests sessions to contact HTTP andHTTPS urls by implementing the Transport Adapter interface. This class willusually be created by the :class:`Session ` class under thecovers.: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 connectionshould attempt. Note, this applies only to failed DNS lookups, socketconnections and connection timeouts, never to requests where data hasmade it to the server. By default, Requests does not retry failedconnections. If you need granular control over the conditions underwhich we retry a request, import urllib3's ``Retry`` class and passthat 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.

或者

defhas_capacity(self):"""Does the engine have capacity to handle more spiders"""returnnot bool(self.slot)

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

1、你不怎么理解的代码

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

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

self.inprogress = set()# requests in progressassertnot self.running,"Engine already running"

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

本文最初发表在www.chinaznyj.com,文章内容属作者个人观点,不代表本站立场。


会员登录

会员登录

登录免费下载全站资源

获取验证码
登录
登录
开发简历

开发简历

简历模板网站自取

入坑需谨慎

入坑需谨慎

高薪完全靠自己

微信赞助-Java帮帮社区

微信赞助-Java帮帮社区

非盈利性学习社区

支付宝赞助-Java帮帮社区

支付宝赞助-Java帮帮社区

将分享做到极致

大公司资讯
文章附图

近日,在美国推出满一年的Facebook视频服务Watch,宣布正式向全球推广,这预示着视频领域中,YouTube...

文章附图

据彭博社北京时间9月19日报道,科技行业最引人注目的法律大战可能正在进入尾声。据高通CEO史蒂夫·莫伦科夫(Ste...

Java帮帮公众号生态

Java帮帮公众号生态

总有一款适合你

Java帮帮-微信公众号

Java帮帮-微信公众号

将分享做到极致

Python帮帮-公众号

Python帮帮-公众号

人工智能,爬虫,学习教程

大数据驿站-微信公众号

大数据驿站-微信公众号

一起在数据中成长

九点编程-公众号

九点编程-公众号

深夜九点学编程

程序员服务区-公众号

程序员服务区-公众号

吃喝玩乐,听学吐画

Java帮帮学习群生态

Java帮帮学习群生态

总有一款能帮到你

Java学习群

Java学习群

与大牛一起交流

大数据学习群

大数据学习群

在数据中成长

九点编程学习群

九点编程学习群

深夜九点学编程

python学习群

python学习群

人工智能,爬虫

测试学习群

测试学习群

感受测试的魅力

Java帮帮生态承诺

Java帮帮生态承诺

一直坚守,不负重望

初心
勤俭
诚信
正义
分享
合作品牌 非盈利生态-优质内容分享传播者
关于我们
友链申请
友链交换:加帮主QQ2524138991 留言即可 24小时内答复  
全站内容非商业用途,内容来源于网友,并遵循 CC BY-NC 4.0 许可,如有异议请联系客服。
会员登录
获取验证码
登录
登录
我的资料
留言
回到顶部