Python开发者文档编程的正确姿势重要性如果你想知道一个人写代码的能力，评论其实是老司机和鲜肉的重要分界线（你有没有观察到你们公司的领导基本都是在开会或者写文档），通常老司机的文档量和代码量的比例是1:1，而新手往往认为写完功能模块就可以完成任务。在生产环境中，需要面对现实中大量复杂的业务逻辑和数据校验，并与各方打通，因此将文档质量和代码质量提升到同样的高度。很多人没有写评论的习惯。他们中的大多数不是因为懒惰。一方面，他们不知道写文档的好处，另一方面，他们也不了解这方面的工具。毕竟，靠人的主动性进行管理远不如靠工具有效。本文介绍如何使用Python注释提高文档编写质量和效率的技巧。在Python的实际生产中，机器学习工作现在看起来就像算法工程师白天的工作，晚上变成了运维+测试。Python一直受到测试工程师和运维工程师的青睐。这里有几个使用注释的经典案例。编写带有注释的单元测试：doctest单元测试是代码开发的重要组成部分，对于错误定位和代码质量非常重要。现在最知名的单元测试框架是Unittest，它借鉴了Java中成熟的单元测试框架JUnit。即使Django对这个框架有特殊的支持，但是在实现Unittest的时候，setup，teardown……，在维护单元测试的时候，往往会觉得力不从心。一个聪明的方法是使用doctest来完成带有docstring注释的单元测试。由于每个方法def后面都是一个测试用例，后面是代码文本，这样我们测试已有代码就很方便了。另一方面，它很容易修改。举个例子：deffactorial(n):"""Returnthefactorialofn,anexactinteger>=0.>>>[factorial(n)forninrange(6)][1,1,2,6,24,120]>>>factorial(30)265252859812191058636308480000000>>>阶乘（-1）回溯（最近的调用）：...值错误：nm必须>=0Factorialsoffloats是可以的，但float必须是精确的整数：>>>阶乘（30.1）回溯（最近的调用）：...ValueError：nm必须是exactinteger（3>0）)265252859812191058636308480000000Itmustalsonotberidiculouslylarge:>>>factorial(1e100)Traceback(mostrecentcallast):...OverflowError:ntoolarge"""importmathifnotn>=0:raiseValueError("nmustbe>=0")ifmath.floor(n)!=n:raiseValueError("nmustbeexactinteger")ifn+1==n:#catchavaluelike1e300raiseOverflowError("ntoolarge")result=1factor=2whilefactor<=n:result*=factorfactor+=1returnresultif__name__=="__main__":importdoctestdoctest.testmod()上面是官网提提供了N的阶乘函数的示例。在文档字符串中，使用>>>符号开始单元测试，然后在新行中输入预期结果。其实就是复制粘贴调试过程和结果。再简单不过了。因此，实现TDD变得非常容易。编写带有注释的API文档：在我们完成机器学习模型后，当我们要对外提供服务接口来贡献我们的算力时，apidoc需要一份完整的API文档。也正是通过API调用，我们可以为我们的模型提供源源不断的验证数据，对于提升模型的效果有着非常实际的意义。对大多数人来说，调用API完成开发是一件幸福的事情，因为我们可以事半功倍地实现强大的功能。但是，当我们需要对外提供API时，会面临不同的考验，比如接口认证、接口设计、版本控制、并发问题、日志埋点……这些都是需要面对的新问题，而使用apidoc可以轻松很好的解决这些API文档中的很多常见问题，相当于通过模板来提升我们的界面设计能力。apidoc为Python提供了一种类似docstring的方式来编写API文档。从语法上看，它类似于R中的roxygen，需要用户以@xxx符号开头，然后编写相关的定义和函数。例如：下面是一个API接口的定义方法，核心部分是路由GET/POST方法名/组参数和调用示例（这年头没有用例的代码都是流氓）"""@api{get}/user/:idRequestUserinformation@apiNameGetUser@apiGroupUser@apiParam{Number}idUsersuniqueID.@apiSuccess{String}firstnameFirstnameoftheUser.@apiSuccess{String}lastnameLastnameoftheUser."""我们可以直接用官方的例子来学习如何使用apidoc。首先下载示例源码gitclonehttps://github.com/apidoc/apidoccdapidoc然后安装apidoc组件sudonpminstallapidoc-g然后使用官方代码制作示例并接入。apidoc-iexample/-ooutput/-ttemplate/openoutput/index.html几个参数含义如下：-i:input，表示输入文件夹-o:output，表示输出文件夹-t:template，表示模板文件，我们可以通过更换模板来修改文档皮肤。在example文件夹下，我们需要在apidoc.json中填写配置文件来定义文档的页眉和页脚部分，其余的文件会被自动识别为API文档的一部分。.由于apidoc的官方文档非常简单明了，这里不强调语法。Apidoc还为我们提供了接口调试功能，实际使用中需要注意：我们需要一个web服务器才能使用这个接口调试功能，同时注意跨域问题。通过版本对比，我们也可以快速查看API接口的变化。需要注意的是，该功能需要我们将历史文档记录保存在该目录下的文件中，通常我们可以将历史评论输出到特定的文件中进行保存。总的来说，API文档的编写虽然不是一件很困难的事情，但是却能体现出系统模块设计和用户体验设计的强大。我们应该对没有代码示例和版本控制的API文档说不。!写带注释的命令行界面：docopt有了docopt，我们可以直接在注释中声明文件的命令行输入参数，而不需要使用argvs变量来捕获输入值再进行判断。这在调用运维脚本或者几个任务调度脚本时特别有用，大大提高了CLI的效率。例如：（此处代码仅供参考）"""用法：fiannceR.pytcp
