文档的最佳实践

文档应该写“要干什么”,“为什么要这么干”,“准备怎么干”。不要写“是怎么干的”。因为需求在变、环境在变,如果把实现的细节写到文档里,将来和代码实现不一致,就会让使用者、维护者迷糊。
所以我们应该用格式化的数据来写,用稳定的数据接口,一次性输出文档、测试、mock 数据。本视频简单演示做法。

指导群里的小伙伴做小项目 应用创意:Chrome 共享首页,有两位同学主动领命,分开前后端就开做。结果我发现他们对文档的处理非常幼稚……所以便有了这样一个分享。

我的观点:

  1. 文档当然要写,但不要用自然语言这样写一大篇
  2. 文档如果不好好维护,将来表现和实际代码不一致,会造成更大的问题
  3. 所以开发者应该用更强的方式约束文档和代码,而不是大家主观协作
  4. 所以我们——尤其在前后端协作的时候——应该写格式化数据结构描述,然后通过编译的方式,用数据结构描述输出文档、测试、Mock Data

下面是视频:

作者: meathill

爱编程,爱旅游,爱吐槽。 今年的目标是完成并运营至少一个 Side Project。 《Electron + Vue 实战开发》龟速创作中……

欢迎吐槽,请勿装死

This site uses Akismet to reduce spam. Learn how your comment data is processed.