php - 如何从里到外记录现有的小型网站(网络应用程序)？

Question

关闭。这个问题是opinion-based .它目前不接受答案。












想改善这个问题吗？更新问题，以便可以通过 editing this post 用事实和引文回答问题.

3年前关闭。




Improve this question




我们有一个在过去 7 个月内开发的“网络应用程序”。问题是，它并没有真正记录下来。需求由 7 个月前初次 session 的一个小项目符号列表组成(它更像是一个“目标”声明，而不是软件需求)。它收集了许多源于小型口头或聊天讨论的功能。

开发商很快就要离开了。他自己写了整件事，他知道每个页面的所有怪癖和基本规则，但没有人真正了解它的用户界面方面；这当然是简单的部分，因为它对用户来说是直观的。但是，如果有人需要对其进行修复或添加功能，那么整个事情就是一个黑匣子。代码有一些最少的注释，当然，Web 应用程序的好处是地址栏为您指明了解决问题或升级页面的正确方向。

但是开发人员应该如何记录这个 Web 应用程序呢？至于从哪里开始，他有点迷茫。作为开发者，您如何为其他开发人员、维护人员和管理级别的用户完整记录您的 Web 应用程序？你使用什么方法，你从哪里开始，你使用什么软件，你有模板吗？

一个重要的想法:它使用 PHP、MySQL 和 jQuery。它有大约 20-30 个主(前端)文件，以及大约 15 个包含文件和一些 Assets 的几个文件夹——所以总的来说它是一个非常小的应用程序。它与 7 个 MySQL 表接口(interface)，每个表都有很好的名称，所以我认为数据库端是不言自明的。有一个 config.inc.php 文件，其中包含常量定义，例如 MySQL 用户详细信息、一些发件人/收件人电子邮件以及 PHP 用于插入电子邮件和页面的 URL(基本上是相对路径和绝对路径)。有一些通过 jQuery 的 AJAX。

如果有任何其他信息可以帮助您帮助我，请发表评论，我很乐意编辑它。

开发商周五离开。但是，他可以将剩余 24 小时的大部分时间用于此文档任务。所以，是的，事情很惨淡，但 24 小时有点……对吧？ :-\

Answer 1

我将首先列出应用程序当前实现的主要功能(更新初始要点)。

然后，对于每个要点，写下与该要点相关的主要要求。

对于每个要求，写下:

关于该特定要求的任何古怪之处

要求在代码中的何处实现(哪些 php、inc 文件、表格)

这将为您提供可追溯性层次结构

功能 => 需求 => 实现

它还将提供一个很好的框架来插入内存和写下陷阱。

然后，注释每个 php 和 inc 页面。

从概述目的和满足上一个列表中的哪些需求(从代码到需求的反向可追溯性)的标题开始。

浏览每个 php/inc 文件并注释主要操作/决策/循环，指示他们试图完成的内容以及假设的任何设计考虑因素(例如“假设输入已在上一步中得到验证”)。

注释源代码时，您可能需要使用诸如 PHPDoc 之类的工具。以便您可以从评论中生成文档。