首页 > 编程笔记 > Python笔记 > Python文档和测试
编写Python开发文档的重要性
为自己的代码做的最重要一件事,就是告诉别人如何使用它,这有可能像只需要说明一点稍微复杂的逻辑那样简单,也有可能像编写 3000 行长的程序介绍那么复杂。我们把这些说明叫做文档。
文档既可能是说明如何使用程序的文件,也可能会内嵌在代码中,它可以包含示例项目、教程或者每个函数的清单。编写文档看上去像是一项占用了编写代码的时间的活动,然而,这却是大多数程序员必须要做的工作。
占用编写代码的时间难道不是一件糟糕的事吗?事实上,文档为每个参与者所节省的时间之多,常常令人难以置信。如果很好地为代码编写了文档,今后接手工作的所有程序员,都能更容易地搞明白代码是做什么的,以及他们可以如何使用代码,他们就能扩展代码来做更多的事情,或者修改所出现的 Bug。
不仅如此,文档在将来可能还会对自己有所帮助。今天看上去很直观的一些代码,明天可能就会令人很困惑。你可能真的忘记了为什么总是需要给出一个参数,或者为什么要用一个
好的文档应该告诉用户想要使用一段代码所需要知道的信息,而且没有废话。试图介绍每种可能的状态或说明所编写的每行代码,会很容易把代码淹没在一个文档中。
过多的文档就像使用新数码相机那 320 页的用户手册一样。你可能不会痛下决心去阅读它。事实却是如此,你可能只会在使用遇到困难时才会从文档中寻找解决方案,但是并不会太在意自己可能错过了数百个其他功能。
好的文档应该是有组织的。其他的程序员会希望在特定的位置有某种特定类型的文档。关于函数能够做什么的说明,应该包含在函数中,并且通常要使用某种特定的格式。安装说明不应该在代码中,而应该位于一个单独的文件中。对于需要些技巧的代码的详细说明,应该在该代码的附近。
既然文档这么有用,那么应该如何编写呢?怎样才能编写出“高大上”的 Python 软件开发文档呢?请大家带着问题继续阅读《如何编写Python软件开发文档(7个技巧)》一节。
文档既可能是说明如何使用程序的文件,也可能会内嵌在代码中,它可以包含示例项目、教程或者每个函数的清单。编写文档看上去像是一项占用了编写代码的时间的活动,然而,这却是大多数程序员必须要做的工作。
占用编写代码的时间难道不是一件糟糕的事吗?事实上,文档为每个参与者所节省的时间之多,常常令人难以置信。如果很好地为代码编写了文档,今后接手工作的所有程序员,都能更容易地搞明白代码是做什么的,以及他们可以如何使用代码,他们就能扩展代码来做更多的事情,或者修改所出现的 Bug。
不仅如此,文档在将来可能还会对自己有所帮助。今天看上去很直观的一些代码,明天可能就会令人很困惑。你可能真的忘记了为什么总是需要给出一个参数,或者为什么要用一个
try/except
子句把函数包围起来。好的文档应该告诉用户想要使用一段代码所需要知道的信息,而且没有废话。试图介绍每种可能的状态或说明所编写的每行代码,会很容易把代码淹没在一个文档中。
过多的文档就像使用新数码相机那 320 页的用户手册一样。你可能不会痛下决心去阅读它。事实却是如此,你可能只会在使用遇到困难时才会从文档中寻找解决方案,但是并不会太在意自己可能错过了数百个其他功能。
好的文档应该是有组织的。其他的程序员会希望在特定的位置有某种特定类型的文档。关于函数能够做什么的说明,应该包含在函数中,并且通常要使用某种特定的格式。安装说明不应该在代码中,而应该位于一个单独的文件中。对于需要些技巧的代码的详细说明,应该在该代码的附近。
既然文档这么有用,那么应该如何编写呢?怎样才能编写出“高大上”的 Python 软件开发文档呢?请大家带着问题继续阅读《如何编写Python软件开发文档(7个技巧)》一节。
所有教程
- C语言入门
- C语言编译器
- C语言项目案例
- 数据结构
- C++
- STL
- C++11
- socket
- GCC
- GDB
- Makefile
- OpenCV
- Qt教程
- Unity 3D
- UE4
- 游戏引擎
- Python
- Python并发编程
- TensorFlow
- Django
- NumPy
- Linux
- Shell
- Java教程
- 设计模式
- Java Swing
- Servlet
- JSP教程
- Struts2
- Maven
- Spring
- Spring MVC
- Spring Boot
- Spring Cloud
- Hibernate
- Mybatis
- MySQL教程
- MySQL函数
- NoSQL
- Redis
- MongoDB
- HBase
- Go语言
- C#
- MATLAB
- JavaScript
- Bootstrap
- HTML
- CSS教程
- PHP
- 汇编语言
- TCP/IP
- vi命令
- Android教程
- 区块链
- Docker
- 大数据
- 云计算