Postado por hlegius em É fato que ninguém nasce sabendo. Fato também que para evoluirmos é bem interessante ler, além de entender, saber separar as coisas e etc., mas a base é a leitura. A todo momento o pessoal fala isso nos fóruns: "leia isto, leia aquilo. Nossa, isso aqui é referência neste assunto".
Vamos centrar mais no "nosso" mundo: você não sabe PHP, mas está interessado em aprender. O que você vai em busca imediatamente ? Referências, manuais e "apostilas", certo ? Seu objetivo com isto é aprender/conhecer algo que ainda não conhece.
Qual é o pré-requisito para tal ? Saber ler, óbvio ! Por mais expressivo que um str_replace("foo","bar", $string); possa parecer, você precisa realmente entender o que acontece ou deixa de acontecer naquela parte.
Você deve estar se perguntando: aonde você quer chegar ?
Simples: se tudo isso que citei é muito óbvio para você, meus parabéns ! Você deve ser um profissional preocupado com a documentação !
Sim, da mesma forma que você precisou ler para entender como funciona a API de reflexão nativa do PHP, o seu colega de projeto precisará ler a documentação daquele Webservice que você fez para o projeto.
Partindo da minha analogia, seu amigo precisa ter como pré-requisito: saber ler e conhecimentos em PHP para poder implementar x)
Pensamento óbvio o meu, claro, claro que sim ! Mas pensa aí rapidinho: quantos códigos nos últimos tempos você pegou totalmente sem documentação, isso sem falar em outros aspectos, como qualidade interna e blablablá [no bom sentido] que profissionais aptos a escrever grandes softwares fazem [Se essa última palavra não faz sentido para você, recomendo ler este livro para entender o que é um grande software]
Aquela velha estória de que quem manja mesmo lê o código e já era caiu por terra. Para um formmail até que pode ser, mas aplicações modularizadas com um modelo bem definido e aplicado e uma chuva de classes trabalhando neste modelo precisa muito mais do que uma simples leitura de código. O mínimo necessário são os comentários do tipo DocBlock além dos comentários inline e por fim e não menos importante Classes, atributos, comportamentos, variáveis locais e constantes com nomes reais do que fazem, recebem ou são.
-
<?php
-
/**
-
* Pretend this is a file
-
*
-
* Page-level DocBlock is here because it is the first DocBlock
-
* in the file, and contains a @package tag
-
* @package pagepackage
-
*/
-
define("almost","Now the Page-level DocBlock is for the page, and the Define has no docblock");
-
?>
Isto é um DocBlock retirado daqui !
Para fechar, eu recomendo fortemente que você caso não conheça, dê uma boa olhada e claro, passe lá e pegue sua cópia gratuitamente dele, o PHPDoc em PHPdoc.org. Não vou me prolongar em explicar o que ele tem ou o que faz. O site está lá completinho.
Veja você mesmo neste exemplo online onde foi gerado o manual do Smarty Template. Ele por si só já diz tudo. Agora é com você 
Por isso eu leio sobre economia! rs
Concordo com vc; não dá pra ir na raça.
Até porque em grandes aplicações nem adianta saber entender só o código nativo; geralmente são usados frameworks e bibliotecas, onde o que importa é o interfaceamento que a sua aplicação faz com ela, e não como ela é implementada!
[]s!
Gostei do ponto de vista , estou atras dessa busca por agora , quero aprender a programar !
Agora , poderia criar um artigo também explicando como interpretar esse criação de documentação !!!
E algo que ainda não achei como vc chega ao modelo usado de chamadas de arquivos ?