gpt4 book ai didi

【python教程入门学习】编写Python开发文档的重要性

转载 作者:知者 更新时间:2024-03-13 08:41:54 25 4
gpt4 key购买 nike

为自己的代码做的最重要一件事,就是告诉别人如何使用它,这有可能像只需要说明一点稍微复杂的逻辑那样简单,也有可能像编写 3000 行长的程序介绍那么复杂。我们把这些说明叫做文档。

文档既可能是说明如何使用程序的文件,也可能会内嵌在代码中,它可以包含示例项目、教程或者每个函数的清单。编写文档看上去像是一项占用了编写代码的时间的活动,然而,这却是大多数程序员必须要做的工作。

占用编写代码的时间难道不是一件糟糕的事吗?事实上,文档为每个参与者所节省的时间之多,常常令人难以置信。如果很好地为代码编写了文档,今后接手工作的所有程序员,都能更容易地搞明白代码是做什么的,以及他们可以如何使用代码,他们就能扩展代码来做更多的事情,或者修改所出现的 Bug。

不仅如此,文档在将来可能还会对自己有所帮助。今天看上去很直观的一些代码,明天可能就会令人很困惑。你可能真的忘记了为什么总是需要给出一个参数,或者为什么要用一个try/except子句把函数包围起来。对于新手小白想更轻松的学好Python基础,Python爬虫,web开发、大数据,数据分析,人工智能等技术,这里给大家分享系统教学资源,架下我尉(同英): 2763177065 【教程/工具/方法/解疑】

好的文档应该告诉用户想要使用一段代码所需要知道的信息,而且没有废话。试图介绍每种可能的状态或说明所编写的每行代码,会很容易把代码淹没在一个文档中。

过多的文档就像使用新数码相机那 320 页的用户手册一样。你可能不会痛下决心去阅读它。事实却是如此,你可能只会在使用遇到困难时才会从文档中寻找解决方案,但是并不会太在意自己可能错过了数百个其他功能。

好的文档应该是有组织的。其他的程序员会希望在特定的位置有某种特定类型的文档。关于函数能够做什么的说明,应该包含在函数中,并且通常要使用某种特定的格式。安装说明不应该在代码中,而应该位于一个单独的文件中。对于需要些技巧的代码的详细说明,应该在该代码的附近。

25 4 0
Copyright 2021 - 2024 cfsdn All Rights Reserved 蜀ICP备2022000587号
广告合作:1813099741@qq.com 6ren.com