Melhor maneira de documento de código AJAX + PHP? [fechadas]

Question

Eu sempre fui para o código de documentação, mas quando se trata de AJAX + PHP, nem sempre é fácil: o código é realmente se espalhar! Lógica, dados, apresentação - o nome dele - são divididos e misturados entre server-side e código do lado do cliente. Às vezes, há também o código do lado do banco de dados (procedimentos armazenados, vistas, etc) fazendo parte do trabalho.

Esta me desafia a vir para cima com uma maneira eficiente para documentar tal código. Eu costumo fornecer uma lista de arquivos .js dentro .php, bem como lista de arquivos .php dentro .js. Eu também faço comentários in-line e descrições de funções, onde eu lista que função é usado por que arquivo e qual saída é esperada. I fazer tarefas semelhantes para procedimentos de banco de dados. Talvez não há um método melhor?

Todas as ideias ou experiências?

Nota:. Esta questão aplica-se a todas as aplicações cliente + do lado do servidor, não apenas Javascript + PHP

Answer 1

Eu acho que é melhor ter uma abordagem hierárquica.

Para obter a documentação de nível api como sobre a função e nível de classe, a documentação em linha escrita no código e gerar a documentação html fora delas usando as muitas ferramentas de documentação lá fora ( JSDoc , phpDocumentor , OraDoclet , etc). Os pontos de bónus se as suas ferramentas doc pode se integrar com suas ferramentas de controle de origem para que possa saltar para linhas específicas de código do seu docs api.

Depois de ter suas ferramentas doc no lugar, começar a gerar a documentação como parte do processo de compilação (você tem um processo de construção, certo?) Para cada nova compilação e empurre a documentação para um local web padrão.

Uma vez que estes docs api estão online, você pode criar um wiki para documentação de alto nível como em navegador> web-> db interações, histórias de usuários, diagramas de esquema, etc. É melhor escrever em breves em prosa ou de bala pontos em alta documentação nível, ligando para docs API e controle da fonte, quando necessário.

Answer 2

Eu acho que o seu método é muito bom. A única coisa é que tudo dentro do arquivo js pode ser lido por outros e, portanto, documentar o que arquivos PHP são usados ??poderia levar a uma falha de segurança, no off chance de que eles podem chegar a um arquivo que retorna algo que não deveria. Além disso, embora não seja um grande negócio, em sites de maior tráfego, o download 500bytes dizer sobre os comentários podem adicionar acima.

Ambos não são grandes, mas apenas pensamentos que eu tinha antes.

Answer 3

Servir o seu javascript (e css) através do PHP - você pode manter seus arquivos de origem juntos por referência cruzada fácil e com uso cuidadoso de cabeçalhos que você pode facilmente lidar com o cache. Isso também permite que você tenha uma versão fonte comentário pesado bem formatado que você pode então condensar ou Ofuscação antes de enviar para o navegador.

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

Para projetos com um monte de javascript, eu uso um sistema de compilação (makefiles) com um javascript minimizer . Como as notas jsmin autor, de decapagem comentários "incentiva um estilo de programação mais expressivo porque elimina o custo de download de, auto-documentação limpo alfabetizados."

O bônus é que jsmin também retira comentários de CSS - assim você pode começar a comentar livremente lá também. (Acho que o uso de classes css é crucial para escrever javascript clara.)

É uma idéia interessante usar o PHP para retirar dinamicamente o código e organizar arquivos javascript. Tenha em mente que uma otimização importante para aplicações web é reduzir solicitações HTTP por isso é muitas vezes sábio para se juntar arquivos javascript menores juntos. (Eu descobri que simplesmente concatenando js minimizados em um único arquivo, funciona muito bem.)