如何描述我的web应用程序的内部工作

Question

我设计了一个web应用程序，该应用程序不仅包含一些复杂的控制器，模型和视图，还包含一些自定义库和数据库。

除此之外，还有一个ajax图层：javascript函数及其相关的服务器端函数。

我已经开发了这个应用程序，我想要一些方法来确保1年后，如果别人拿起它，有一些对逻辑流程的引用。

这是否有工具？有没有人有过这个问题？

Answer 1

一个好的开始是在代码库变得太大之前开始使用PHP Documentor（PHPDoc）。即使这样，回去并标记你的类也不难。PHPDoc将抓取代码库并生成文档，通常是一组基于Web的（HTML）文档，但你也可以生成PDF等等。函数，方法，类等将链接到代码的相关元素。我说在它变得太大之前，因为你会想回去添加评论标签来增强文档的输出。 PHPDocumentor（PHPDoc）可以在这里找到http://www.phpdoc.org/ ，信息和教程可以在网络上找到。如果你已经走了这么远用PHP那么想必你一定已经注意到了这样的评论...（DOC块）

/** 
*@todo something I need to do 
*@param [type] [$varname] [description] 
* 
*/ 

这些标签/文档块是由PHPDoc的解析，并且是非常有用的......最IDE对于使用DocBlocks也非常友好，并且有时会根据代码中的DocBlocks增强代码提示等。

对于数据库...有很多工具和teqniques但这里是一个建议...

数据库可以通过，将建立图的工具来描述。例如，使用MySQL时，您可以安装MySQL Workbench，然后这将为您提供连接到数据库的工具，并构建一个类似于此页面上的图片的图表... http://forge.mysql.com/wiki/MySQL_Workbench，以及许多其他用于反向查看的工具，工程和/或设计，ORM工具等等。有时只是图表和现有的数据库可以是非常有用的，尤其是当有很多关系。 MySQL Workbench将为您提供将图表发送至PDF或图像的选项。所有非常有用。

这不仅会帮助未来的开发人员，但这些工具也会帮助你自己。我们都很惊讶地发现，在几周，几个月等没有看到代码后我们会忘记。星期一早上，即使是一个繁忙的周末，也可能会让开始缓慢。

对于我最后的建议......我将在这里简单一些，但请注意bug /问题跟踪。网上有很多，或者你可以自己安装。有些随版本控制（比如在GitHub，Unfuddle，BitBucket等）......或者你可以自己安装。我发现Bugzilla安装起来非常简单，如果你使用Ubuntu，它很适合在版本库中安装并且轻松安装。

Answer 2

这肯定不是你正在寻找的整个答案，但我总觉得非常有用的是一个适当的文档！是的，有一些非常好的工具，例如PHPDoc。这部分允许您创建工作流程的文档，至少可以解释您到底在做什么。

再往下看，你可能只是简单地用普通英语解释它是怎么回事flows。如果它是一个非常大的应用程序，你甚至可以考虑创建自己的wiki！

Answer 3

这通常称为“as-built”文档;互联网上有大量的信息。

我的首选是将文档分成几个部分;每一个都和另一个一样重要，但是你不需要花费相同的时间。

功能设计

什么应用程序该怎么办？什么是预期的行为？关键的用户旅程是什么？

我喜欢使用use cases或用户故事为此，在不同程度的细节。系统环境图也有帮助。用例可以是视觉的和文本的;几个小时是经常不足以形容一个简单的应用程序

非功能性需求

比如像安全性，性能，浏览器的支持，SEO，可访问性 - 列出你并没有装在的东​​西应用程序，所以未来的开发人员知道要担心什么以及要测试什么。

概念设计

内置，识别主要部件，集成点，并依赖该系统的高度概括。

详细设计

这是位是最随时更改，并保持最大的痛。使用PHPDoc是保持最新状态的好方法。

验收测试

即使你不买测试驱动的开发，使未来发展与测试应用程序的工作原理是，让他们理智一个伟大的方式方法。理想情况下，验收测试将自动/脚本化（例如使用硒）。

已知错误

提供已知错误的未来开发商名单被拉出自己的头发阻止他们......

所有这一切都可以是一个大量的工作 - 这么多球队用“低形式”沟通的方式 - 维基白板的照片，甚至视频的团队解释设计

更正式的，也有像UML标准，以帮助捕获文档在一个行业标准的方式

。