10

我一直喜欢编写代码文档，但是当涉及到 AJAX + PHP 时，这并不总是那么容易：代码真的很分散！逻辑、数据、表示——你可以命名它——在服务器端和客户端代码之间被分割和混合。有时还有数据库端代码（存储过程、视图等）在做部分工作。

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

有什么想法或经验吗？

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

4

4 回答 4

4

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

这两个都不大，只是我以前的想法。

于 2008-10-05T06:39:17.553 回答
3

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

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

准备好文档工具后，开始为每个新构建生成文档作为构建过程的一部分（您有构建过程，对吗？），并将文档推送到标准 Web 位置。

一旦这些 api 文档上线，您就可以为高级文档创建一个 wiki，例如浏览器->web->db 交互、用户故事、模式图等。最好为高级文档编写简短的散文或要点，必要时链接到 api 文档和源代码管理。

于 2008-10-05T15:15:17.747 回答
1

通过 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(); 
}
于 2008-10-10T15:34:41.890 回答
0

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

好处是 jsmin 还从 CSS 中删除了评论——所以你也可以在那里自由地开始评论。（我发现使用 css 类对于编写清晰的 javascript 至关重要。）

使用 PHP 动态剥离代码并组织 javascript 文件是一个有趣的想法。请记住，Web 应用程序的一项重要优化是减少 HTTP 请求，因此将较小的 javascript 文件连接在一起通常是明智的。（我发现简单地将最小化的 js 文件连接到一个文件中，效果很好。）

于 2008-11-12T15:12:04.700 回答