Question

我一直都在记录代码，但是当涉及到AJAX + PHP时，它并不总是那么简单：代码真的很分散！逻辑，数据，演示 - 您的名字 - 在服务器端和客户端代码之间进行拆分和混合。有时，还有数据库端代码（存储过程，视图等）执行部分工作。

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

任何想法或经历？

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

Answer 1

我觉得你的方法非常好。唯一的事情是js文件中的所有内容都可以被其他人读取，因此记录使用哪些PHP文件可能会导致安全漏洞，因此他们无法获得返回不应返回的文件。此外，虽然不是什么大问题，但在流量较高的网站上，下载说500条评论可以加起来。

这些都不大，但只是我以前的想法。

Answer 2

我认为最好采用分级方法。

对于函数和类级别的api级文档，在代码中编写内联文档，并使用许多文档工具从中生成html文档（JSDoc，phpDocumentor，{ {3}}等。如果您的文档工具可以与源代码管理工具集成，那么您可以从api文档跳转到特定的代码行。

一旦你有了doc工具，就开始为你的构建过程生成文档（你有一个构建过程，对吗？）为每个新构建生成文档并将文档推送到标准Web位置。

一旦这些api文档在线，您就可以为高级文档创建一个wiki，例如browser-＆gt; web-＆gt; db交互，用户故事，架构图等。最好写一篇简短的散文或要点对于高级文档，必要时链接到api文档和源代码控制。

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(); 
}

Answer 4

对于包含大量javascript的项目，我使用带有javascript minimizer的构建系统（makefile）。正如jsmin作者所指出的那样，剥离评论“鼓励更具表现力的编程风格，因为它消除了干净，有文化的自我文档的下载成本。”

奖金是jsmin还会删除CSS的评论 - 所以你也可以在那里自由开始评论。（我发现使用css类对于编写清晰的javascript至关重要。）

使用PHP动态删除代码并组织javascript文件是一个有趣的想法。请注意，对于网络应用的重要优化是{{3}}，因此将较小的javascript文件加在一起通常是明智之举。（我发现简单地将最小化的js文件连接成一个文件，效果很好。）

记录AJAX + PHP代码的最佳方式？

4 个答案: