向开源项目学习如何写技术文档和高质量代码

每个程序员都不喜欢写文档,但同时也吐槽别人不写文档,文档写的烂、不清晰。其实,很多程序员并不会写技术文档。写文档有什么作用?作用主要有两个,一个是团队新成员可从此文件中快速获悉项目大致情况,另一个是部署项目时可以作为参考。

不会写技术文档,没关系,学就可以了。向谁学是个问题,现在开源软件正在吞噬整个世界,GitHub 上有着无数的优秀开源项目,优秀的项目肯定不会缺少文档,代码质量肯定不会差,参考着学习肯定不会错。

对于程序员来说,文档基本都是 Markdown 类型的文档比较多,如果你还不知道什么是 Markdown ,那赶紧学习一下吧,很简单的。

小项目比较简单,一般一个 README.md 文件就可以,记录一下项目所需的运行环境、比如操作系统,编程语言版本、框架版本、依赖库、依赖组件、注意事项等等。

中型项目可以在项目文件中新建 docs 目录,然后相关的技术文档都可以放在里面,比如项目背景、项目目标、版本需求迭代信息等等。

大型项目技术文档就比较复杂了,一般都是独立安排项目负责人、或者产品负责人统一编写。

现在前后端分离开发模式非常流行,约定好数据格式。后端提供 RESTful API,前端根据文档对接联调,并行开发,提高开发速度。

一份完善的 API 文档应该具备什么内容?

  1. 基础信息
  2. 请求地址
  3. 请求方式
  4. 请求参数
  5. 响应数据
  6. 备注信息

每门语言、框架,不同的公司、团队,都会有编码规范,比如 PHP 的 PSR 规范,JavaScript 的 Standard 和 Airbnb 。只要平时开发时多注意,项目代码质量就肯定不会差,还有就是命名问题,少用无意义的变量,比如 data info 之类。

多学习 23 种设计模式,多用设计模式,熟记面向对象编程的三大特性(封装、继承、多态)、原则(单一责则原则、开闭原则、里式替换原则、接口隔离原则、依赖倒置原则)。让项目代码具有可读性高、可维护性强、可扩展性好,代码清晰易懂、简洁。

一边版本迭代开发一边重构、优化、扩展,甚至重写,重写功能模块而非整个项目,不要过度设计。

打赏作者

您将是第一位评论人!

提醒
avatar