理念

smart-doc设计理念

• 拥抱生成主流框架标准规范，支持主流框架特性。
• 减少不必要的tag设计，减少不必要的学习成本。
• 引导用户尽量遵循行业的最佳实践规范。

smart-doc适用设计先行的开发吗？

一些老派的程序员或者所谓有多年经验的架构师觉得，smart-doc这种基于代码扫描工具对于设计先行的开发模式并没有什么作用。 真的是这样的吗？我们来看看吧。

设计先行模式

• 由比较有经验的人编写设计文档和接口协议。
• 完成设计后主要由业务开发工程师根据设计文档开发业务逻辑。
• 架构师也可以像国外一些架构师一样，直接定义好程序的接口框架，然后交付给业务工程师填充业务代码。

设计先行通常在成熟的开发团队中。在代码先行模式下，接口协议虽然在设计阶段都已经定义好。但是smart-doc仍然很有用。

• 设计的好的接口协议后期的持续更新遗漏，仍然是个问题，人性本是懒惰的。smart-doc能够保持文档和代码的一致性。
• 一个新成员进入团队看代码，html的文档明面比word写的更方便跟踪。新成员完全可以直接上手打开debug文档页面调试熟悉业务。
• smart-doc由于采用源码分析，对代码的标准度要求高于其他工具，使用这个工具直接就能统一团队风格。
• 还可以基于smart-doc定制开发，将文档输送到yapi这样类似的接口文档管理中。

目前国内主流的设计先行的文档方式，主要就是word或者是markdown。word的翻页对接口展示很不友好。

代码先行

代码先行的这种模式，利用smart-doc天然就可以一边写代码一边出接口文档。然后利用smart-doc对代码的规范要求严格度。 完全可以保证团队代码风格不会出现很大差异。

代码先行在很多团队是有弊端的，代码先行特别是对大型系统，对代码编写者能力要求很高。 代码和业务的结合能力需要非常强，能够考虑到扩展和业务边界。代码先行这种，也可以走另外一种路线， 团队的架构师直接搭建好项目框架后，定义好接口框架代码，填充业务逻辑部分全部空出来。有了接口，smart-doc已经可以扫描生成接口文档了

总结

总之，使用文档工具和团队采用哪种模式并没有半点关系。工具是为了在某些方面去帮助团队更好的完成工作或者是提高效率。 作为技术人员也要向前看，总会有新的技术、新的框架、新的工具出来去解决过去的一些问题。对新事物持有好奇心也是一种人生态度。

我是菜鸟能参与开源吗？

开源软件最重要的指标并非是技术，社区的活跃度和代码贡献者数量才是衡量开源软件能够持续发展的指标。 因此只要你有时间和愿意参与贡献，smart-doc的作者基本都指导你怎么去修改issue。

smart-doc的核心维护者中也有同学是从在校生开始加入开发，并在后面成功拿到国内某大厂offer的。 因此我们非常欢迎愿意参与开源的同学加入，即便你是菜鸟都不用担心。 smart-doc当前已经被国内许多一二线大厂所采用，未来只会更多。参与开源对菜鸟和萌新的帮助都是蛮大的。