Python中的注释_python注释

见贤思齐

文章目录简述注释类别单行注释多行注释中文注释注释快捷键文档字符串注释注释示例函数和方法类块注释和行注释简述代码注释对于代码后期维护很重要。Python中有哪些注释的规则，以及如何能高效简洁的使用注释，在此进行介绍和学习。注释类别类别符号可能问题单行注释#多行注释‘’’‘’’可能和多行字符串混淆中文注释#coding=utf-8代码中尽量不用中文注释注释快捷键IDE工具中文档字符串注释‘’’‘’’需要Python零基础学习资料的伙伴，可以在公众号【码农资料库】中回复【py】自行领取包括以下学习资料：①Python所有方向的学习路线图，清楚各个方向要学什么东西②Python课程视频，涵盖必备基础、爬虫和数据分析③Python实战案例，学习不再是只会理论④Python电子好书，从入门到高阶应有尽有⑤华为出品独家Python漫画教程，手机也能学习⑥历年互联网企业Python面试真题,复习时非常方便单行注释使用很灵活，和一般脚本中用到的类似。但是行数很多时可能会要一行一行去注释比较麻烦。多行注释三个单引号’''进行注释，这种方式也比较常见，但是需要和多行字符串区分。中文注释在python编写代码时，如果避免不了用到中文，需要在文件开头加上中文注释。比如创建一个pythonlist，在代码上面注释上它的用途，如果开头不声明保存编码的格式是什么，那么它会默认使用ASKII码保存文件，这时如果代码中有中文就会出错了，即使你的中文是包含在注释里面的。所以加上中文注释很重要。#coding=utf-8或者：#coding=gbk注释快捷键一般python开发调试的IDE中，都会有这个功能，比如Ctrl+/可以快速注释和取消注释。在Eric中，直接有两个图标按钮，可以将选中的内容进行快速的注释和取消注释。文档字符串注释Python的一种独一无二的的注释方式。文档字符串是包,模块,类或函数里的第一个语句。这些字符串可以通过对象的__doc__成员被自动提取,并且被pydoc所用。(你可以在你的模块上运行pydoc试一把,看看它长什么样)。对文档字符串的惯例是使用三重双引号”“”(PEP-257)。一个文档字符串应该这样组织:首先是一行以句号,问号或惊叹号结尾的概述(或者该文档字符串单纯只有一行)。接着是一个空行，接着是文档字符串剩下的部分,它应该与文档字符串的第一行的第一个引号对齐。注释示例函数和方法一个函数必须要有文档字符串,除非它满足以下条件:外部不可见非常短小简单明了文档字符串应该包含函数做什么,以及输入和输出的详细描述.通常,不应该描述”怎么做”,除非是一些复杂的算法.文档字符串应该提供足够的信息,当别人编写代码调用该函数时,他不需要看一行代码,只要看文档字符串就可以了.对于复杂的代码,在代码旁边加注释会比使用文档字符串更有意义.关于函数的几个方面应该在特定的小节中进行描述记录，这几个方面如下文所述.每节应该以一个行开始.行以冒号结尾.除行外,节的其他内容应被缩进2个空格.Args:列出每个参数的名字,并在名字后使用一个冒号和一个空格,分隔对该参数的描述.如果描述太长超过了单行80字符,使用2或者4个空格的悬挂缩进(与文件其他部分保持一致).描述应该包括所需的类型和含义.如果一个函数接受_foo(可变长度参数列表)或者**bar(任意关键字参数),应该详细列出_foo和**bar.Returns或者Yields:用于生成器)描述返回值的类型和语义.如果函数返回None,这一部分可以省略.Raises:列出与接口有关的所有异常.deffetch_bigtable_rows(big_table,keys,other_silly_variable=None):"""FetchesrowsfromaBigtable.RetrievesrowspertainingtothegivenkeysfromtheTableinstancerepresentedbybig_table.Sillythingsmayhappenifother_silly_variableisnotNone.Args:big_table:AnopenBigtableTableinstance.keys:Asequenceofstringsrepresentingthekeyofeachtablerowtofetch.other_silly_variable:Anotheroptionalvariable,thathasamuchlongernamethantheotherargs,andwhichdoesnothing.Returns:Adictmappingkeystothecorrespondingtablerowdatafetched.Eachrowisrepresentedasatupleofstrings.Forexample:{'Serak''RigelVII','Preparer'),'Zim''Irk','Invader'),'Lrrr''OmicronPersei8','Emperor')}Ifakeyfromthekeysargumentismissingfromthedictionary,thenthatrowwasnotfoundinthetable.Raises:IOError:Anerroroccurredaccessingthebigtable.Tableobject."""pass12345678910111213141516171819202122232425262728293031类类应该在其定义下有一个用于描述该类的文档字符串.如果你的类有公共属性(Attributes),那么文档中应该有一个属性(Attributes)段.并且应该遵守和函数参数相同的格式。classSampleClass(object):"""Summaryofclasshere.Longerclassinformation....Longerclassinformation....Attributes:likes_spam:AbooleanindicatingifwelikeSPAMornot.eggs:Anintegercountoftheeggswehavelaid."""def__init__(self,likes_spam=False):"""InitsSampleClasswithblah."""self.likes_spam=likes_spamself.eggs=0defpublic_method(self):"""Performsoperationblah."""12345678910111213141516171819块注释和行注释最需要写注释的是代码中那些技巧性的部分.如果你在下次代码审查的时候必须解释一下,那么你应该现在就给它写注释.对于复杂的操作,应该在其操作开始前写上若干行注释.对于不是一目了然的代码,应在其行尾添加注释。#Weuseaweighteddictionarysearchtofindoutwhereiisin#thearray.Weextrapolatepositionbasedonthelargestnum#inthearrayandthearraysizeandthendobinarysearchto#gettheexactnumber.ifi&(i-1)==0:#trueiffiisapowerof21234567为了提高可读性,注释应该至少离开代码2个空格.另一方面,绝不要描述代码.假设阅读代码的人比你更懂Python,他只是不知道你的代码要做什么。#BADCOMMENT:Nowgothroughthebarrayandmakesurewheneverioccurs#thenextelementisi+1123-END-