LA CLASE

Un ejemplo de uso

• Haber programado al menos el reloj despertador
• Haber tenido que explicarle al menos a tu mama como se programaba la tele
• Haber tenido que explicarle a algún cliente por correo que su página web es mejor sin flash
• Haber tenido que realizar algún manual de usuario
• Haber tenido que explicar por msn como conectar un pc a internet
• Realizar un mapa a alguien para que llegue a alguna parte
• Haber escrito a una polola en una carta las razones por las que no quieres estar con ella
• Haber tenido que dejar un papel explicando que el almuerzo lo dejaste listo y que en la olla grande esta el plato fuerte, en la chica la sopa y en el refri la ensalada
• Escribir un cheque

¿Qué tiene que ver todo esto con Natural Docs?

, Bueno si se fijan, todas las opciones exceptuando las 2 primeras, son acciones en las que has tenido que dejar constancia, tanto en papel, como en digital, de algún procedimiento o acción que realizaste.  Ahora por otra parte, cuando programas o realizas proyectos de software también debemos dejar constancia de lo que hemos realizado, esto se realiza por varias razones: Mejorar la comprensión del problema, Tener registro de lo que se realizó, Poder mejorarlo en el futuro,  Pensar en los que tomaran el código en futuras generaciones( Uno de los mas importantes :p), etc. Todo lindo hasta aquí pero ¿A los computines les gusta realizar esta tarea?, la respuesta obviamente es no, muchas veces llega a ser un martirio, otras no hay tiempo y otras simple y llanamente nos hacemos los lesos y no la hacemos . ¿Alternativas?, si,  buscar metodologías agiles de desarrollo, las cuales no se basan( no se mal entienda, no las dejan de lado) en la documentación y prefieren dar prioridad a escribir el código, la comunicación con el cliente entre otras. En mi trabajo nosotros utilizamos estas formas de trabajar, pero esto trae consigo que muchas veces no tienes idea nisiquiera de cuál es la magnitud de lo que estás desarrollando y el código que están realizando llega a ser mostruosamente grande.   Por todas estas razones una forma de crear documentación y no "invadir" en demasía al programador su "valioso" tiempo es utilizar los mismos comentarios que el utiliza en su código para generar una documentación que permite observar funciones, clases, métodos, con sus respectivos atributos y otras cosas que puedan tener.

Ahora a lo que vinimos, despues de esa introducción, vamos a revisar uno software que te toma los comentarios en el código y los transforma en una documentación de muy buena calidad .

Natural Docs

Desarrollado por Greg Valure es un generador de documentación escrito en PERL. Su forma de uso es muy simple( Suponiendo que estas en linux y tienes instalado PERL) bajamos el archivo comprimido desde aquí(en la versión estable actual 1.4).  Una vez que descomprimimos el interior te darás cuenta que posee una serie de archivos y carpetas,junta todo en una carpeta por ejemplo con nombre "NaturalDocs". Ahora le das permiso de ejecución al archivo NaturalDocs ( chmod 755 NaturalDocs), con esto ya estamos casi listos para tener nuestra documentación, pero aún faltan algunas cosas por responder.

¿Soporta todos los lenguajes de programación?

Casi , bueno en realidad en la página de NaturalDocs aparece que soporta 19 lenguajes, pero existe un truco, si leen bien la documentación existe la posibilidad de que se agreguen mas lenguajes de manera muy simple, solo debes en un archivo de configuración darle la extención de los archivos y la forma en que se comenta.

¿Los comentarios no deben tener alguna estructura?

Jejeejej, creian que todo iba a ser tan fácil, pero no se preocupen no es la gran cosa. Por ejemplo si queremos comentar una clase

/*
Class: Counter
A class that manages an incrementing counter.
*/
class Counter
{
public:
/*
Constructor: Counter
Initializes the object.
*/
Counter()
{ value = 0; };
/*
Function: Value
Returns the value of the counter.
*/
int Value()
{ return value; };
/*
Function: Increment
Adds one to the counter.
*/
void Increment()
{ value++; };

protected:
/*
Variable: value
The counter's value.
*/
int value;
};

Como ven no es nada del otro mundo y estoy seguro que muchos de ustedes ya usan comentarios parecidos, ahora existen muchas otras formas de realizar esto y darle mas potencia a la documentación por ejemplo miren con una función

/*
 * Function: Multiplicar
 *
 * Multiplica dos enteros.
 *
 * Parameters:
 *    x - El primer entero.
 *    y - El segundo entero.
 *
 * Returns:
 *    El producto de ambos enteros.
 *
 * Ver también:
 *

 */

int Multiplicar (int x, int y)
   {  return x * y;  };

Ahora le dimos una breve descripción de la funcion, que los parametros que recibe son x e y, que es lo que retorna y que esa función esta relacionada con otra, la idea es que todo eso despues queda reflejado en la documentación generada.

La gamma de diferentes cosas que puedes realizar con los comentarios descubranlos en la pagina del soft.

Ahora como ejecuto tal maravilla.

Bueno esto es muy simple, anteriormente le habíamos dado permisos de escritura al script NaturalDocs, bueno ahora debemos ejecutarlo con los siguientes parámetros como mínimo

NaturalDocs -i [input (source) directory]
-o [output format] [output directory]
-p [project directory]
[options]

Como eso no dice mucho un ejemplo

NaturalDocs -i home/tuto/My Project/Source
-o FramedHTML home/tuto/My Project/Docs
-p home/tuto/My Project/Natural Docs

Un poco de explicación: La primera dirección que le damos es la carpeta donde tenemos el código que queremos documentar, la segunda direccion es la carpeta donde guardaremos nuestra documentación y la tercera es una carpeta que debemos crear para que NaturalDocs escriba unos archivos( como una carpeta temporal). Existen muchas otras opciones que puedes agregarle pero eso véanlo aca y eso es todo, el soft se encarga de todo, es muy configurable y puedes crear documentaciones muy profesionales ,algunos ejemplo aquí.

Ahora una última pregunta para terminar

¿Existen otros documentadores de código?
Por supuesto y algunos muy o más buenos que este( lo publiqué porque a mi me gusta mucho este soft), por ejemplo aquí puedes ver una comparativa entre los más populares

Bueno eso por hoy

El link de la página es LINK

Espero les sirva

saludo tuto

Editores de código

NOTEPAD++

El clásico editor de windows "upgradeado" un millón de veces . Realmente es un gran editor, el soporte de una lista interminable de lenguajes te permite trabajar en muchos archivos y de diferentes cosas ( por ejemplo, html, css y js) al mismo tiempo, yo sé que esto lo puedes lograr con una serie de otros programas, pero sinceramente en ningún otro he visto tanto soporte de diferentes lenguajes y en tan poco peso( Kb). Su manejo de tags es otra gracia, ya que en lo personal no me gusta los editores que te autocompletan los tags de html por ejemplo, para mi es un poco incomodo, en cambio aca lo que realiza notepad++ es ir remarcando el tags que estas cerrando al momento que lo vas escribiendo. Las sugerencias por parte de los editores a lo que vamos escribiendo también es diferenciador acá, ya que la opción está, pero solo saldrá cuando nosotros queramos ya que combinando la tecla Crtl+Barra espaciadora te aparecerá lo que Notepad++ te sugiere, esto lo encuentro super útil ya que a veces el proceso de abrir la sugerencia por parte de otros editores hace que se produscan lags al momento de escribir. Trae un buscador que permite realizar estas búsquedas en archivos, por ejemplo le damos una palabra y una carpeta en donde buscar y nos dará todos los resultados encontrados, muy buena opción. El resto de las opciones les toca a ustedes encontrarlas, son muchas y se necesitaría un post completo para explicarlas todas, lo importante es que es muy bueno y totalmente recomendable.

Geany

Este editor lo utilizo cuando uso Linux( si lo reconosco, a veces uso windows), me gusta al igual que Notepad++ porque es muy liviano y puedes realizar muchas cosas. Por ejemplo algunos de los lenguajes soportados son C, Java, JavaScript, PHP, HTML, CSS, Python, Perl, Ruby, Pascal y Haskell (según Wikipedia).  Tiene características muy parecidas a Notepad++, pero la diferencia es que al estar hecho en GTK2 tiene versiones en linux y windows. Soporta projectos y tiene una terminal incluida, muy bueno cuando quieres ir compilando de inmediato.

VIM

Hablar de Vim es hablar de un grande entre los grandes,  sucesor del editor de los sistemas Unix VI, tiene todo lo que un programador necesita y de forma rápida y optimizada. Al principio un poco complicado de utilizar, a medida que se va tomando "ritmo" el potencial crece y crece, sorprende  por la gran cantidad de funcionalidades que posee y de lo sencilla que es su manera de editar los textos. A diferencia de los anteriores editores Vim se utiliza en una consola de comandos, teniendo que realizar la mayoría de las opciones mediante la combinación de teclas. La posibilidad de poder formatear el texto mediante expresiones regulares es muy potente y se pueden obtener resultados sorprendentes con unas pocas intrucciones. Estas son solo algunas características, se podrían escribir 1000 posts para eso, como conclusión se podría decir que si no tienes mucha experticia en el manejo de consolas de comandos, primero prueba uno de los editores anteriores, pero sí aún te gustan los desafíos adelante, totalmente recomendado.

Sin duda existen mas de 1 millón de editores más que podrían utilizar( por ejemplo se me viene Emacs a la cabeza), pero con cualquiera de estos tres puedes comenzar sin problemas, si tienes algún otro que te guste anótalo en los comentarios( Recuerda que deben ser libres ).

En el próximo post veremos editores de imágenes libres.

Espero les haya servido

Saludos tuto