记录AJAX + PHP代码的最佳方法是什么？

Question

我一直支持对代码进行文档化，但涉及 AJAX + PHP 时并不总是容易的：代码非常分散！逻辑、数据、展示 - 你可以说 - 在服务器端和客户端代码之间被分割和混合。有时还有数据库端的代码（存储过程、视图等）承担部分工作。

这促使我想出了一种有效地记录这种代码的方法。我通常会在 .php 文件中提供 .js 文件列表以及在 .js 文件中提供 .php 文件列表。我还进行内联注释和函数描述，其中列出了哪个文件使用了哪个函数以及期望的输出内容。对于数据库程序，我也执行类似的任务。也许还有更好的方法？

任何想法或经验？

注：这个问题适用于任何客户端+服务器端应用程序，不仅仅是 Javascript+PHP。

- DV

Answer 1

我认为你的方法相当不错。唯一的问题是js文件中的所有内容都可以被他人读取，因此记录使用了哪些PHP文件可能会导致安全漏洞，如果他们能够访问返回不应该返回的文件。另外，在高流量网站上，下载500字节的注释可能会累积成很大的负担，虽然这并不是什么大问题。

这两个问题都不算太大，只是我之前想过的一些想法。

- Darryl Hein

Answer 2

我认为采取分层方法是最好的。对于像函数和类这样的api级别文档，可以在代码中编写内联文档，并使用许多文档工具（JSDoc，phpDocumentor，OraDoclet等）生成html文档。如果您的文档工具可以与源代码控制工具集成，那么您可以从api文档跳转到特定的代码行，这将获得额外的加分。

一旦您准备好了文档工具，就可以在每个新版本构建过程中生成文档，并将文档推送到标准的web位置。

一旦这些api文档在线上，您可以为高层次文档创建维基，例如浏览器->Web->数据库交互、用户故事、模式图等。对于高层次文档，最好用简要的散文或项目符号书写，必要时链接到api文档和源代码控制。

- clofresh

Answer 3

通过PHP提供您的JavaScript（和CSS）-您可以将源文件保持在一起以便于交叉引用，并且通过仔细使用标头，您可以轻松处理缓存。这样做还可以让您拥有一个漂亮格式化的注释版本，然后可以在发送到浏览器之前压缩或混淆它。

function OutputJs($Content) {
    ob_start();
    echo $Content;
    $expires = DAY_IN_S;
    header("Content-type: x-javascript");
    header('Content-Length: ' . ob_get_length());
    header('Cache-Control: max-age='.$expires.', must-revalidate');
    header('Pragma: public');
    header('Expires: '. gmdate('D, d M Y H:i:s', time()+$expires).'GMT');
    ob_end_flush(); 
}

- Ken

Answer 4

对于有大量JavaScript的项目，我使用一个构建系统（makefiles）和JavaScript缩小器。正如jsmin作者所指出的那样，去除注释“鼓励更具表现力的编程风格，因为它消除了干净、文学的自我文档的下载成本。”

奖金是jsmin还从CSS中删除注释——所以你也可以在那里自由地进行评论。（我发现使用CSS类对于编写清晰的JavaScript至关重要。）

使用PHP动态剥离代码并组织JavaScript文件是一个有趣的想法。请记住，Web应用程序的一个重要优化是减少HTTP请求，因此通常明智的做法是将较小的JavaScript文件合并在一起。（我发现简单地将缩小的JS文件连接成一个文件非常有效。）

- Jason Moore