Pablo César escreveu:
comandos e funções que ainda não foram postadas no projeto, as mais capciosas ficariam com o mestre Claudio Soto, e etc...
Muitas vezes, a carência de documentação extensa não acompanha com o desenvolvimento. Eu desejo que Claudio continue com o seu trabalho, longe de ele ficar documentando. Não que ele não saiba, senão pela razão que tem muita gente que pode fazer isso.
1) El desarrollador deberÃa solo crear una documenta mÃnima con el prototipo de la función y una breve descripción de la misma y sus parametros
2) la documentación de referencia del lenguaje suele ser creada en una segunda etapa por un grupo de expertos en base a la doc del punto 1 y va destinada a programadores avanzados.
3) por último en base a la doc del punto 2 se crea una documentación más accesible para el usuario final escrita por gente con capacidad didáctica.
Pero hay que tener cuidado en permitir que cualquiera documente, porque si no tiene el suficiente dominio del lenguaje puede crear una documentación confusa y equivocado por mejor buena voluntad que tenga.
Es por este motivo que la mayorÃa de los proyectos open source no tienen buena documentación, porque todo lo tiene que hacer el desarrollador, y siempre prioriza el desarrollo del código al desarrollo de la documentación, y como hay carencia de doc oficial buena empiezan a aparecer doc de todo tipo escritas por quien sabe quien.
Las companias comerciales tienen suficientes recursos económicos como para formar los diferentes equipos que se requiere para desarrollar el proyecto, además cuentan con supervisores y jefes de proyectos que controlan que desde el código hasta la documentación todo encaje perfectamente y en forma armónica. Y como frutilla de la torta siempre publican libros que van destinados a diferente público, desde el iniciante hasta el programador avanzado. La publicación de libros de texto es lo que hace la diferencia en la popularidad de los lenguajes.
Lenguajes espantosos que no aportan absolutamente ninguna ventaja son muy populares porque existe muchos libros sobre ellos, un buen ejemplo es el BASIC y toda su familia. El Pascal como lenguaje es 10 veces mejor pero muy pocos lo conocen. Y después que te acostumbras al desorden del BASIC cuando llegas a un lenguaje rÃgidamente estructurado como el Pascal no lo querés ni ver, aunque para desarrollar un proyecto de mediano a grande porte sea 10 veces mejor porque al ser muy estructurado se evitan muchos errores de lógica.
Lo mismo pasa con las Clases de los lenguajes, su potencial es enorme pero la doc es escasa en relación a la programación estructurada clásica y la gente opta por ignorarla simplemente porque no la comprende. Además existe otro problema con las Clases es que muchos de sus defensores crean Clases hasta para lo que no es necesario y terminan cayendo en la trampa de los que no les gusta las Clases, lo que surgió para facilitar la vida de proyectos de mediana a grande envergadura termina siendo un dolor de cabeza con Clases que repiten código, que están mal definidas, que se superponen, etc.
La clase es una herramienta más, es nada más y nada menos que un tipo de objeto (estructura) definido por el usuario que tiene propiedades (datos) y metodos (funciones que hacen algo con esos datos) diseñado para mejorar la seguridad en el acceso a sus datos y para darle claridad al código. Cuando es bien empleada es de un valor incalculable, cuando se emplea en forma innecesaria es una pérdida de tiempo que lo único que logra es crear un código difÃcil de entender y por lo tanto difÃcil de mantener.