Como escribir comentarios para la documentación con el Javadoc

How to Write Doc Comments for the Javadoc Tool

Este es un tutorial de la convenciones usadas para la creación de comentarios en los programas que creamos en los projectos. Este documentación es importante porque será utilizado por otros programadores (y en algunos casos por nosostros mismos), para el desarrollo.

Este documento trara de como crear la documentación para que el javadoc pueda crear una documentación de nuestro código de manera correcta (como la del API de J2SE por ejemplo).

Obviamente el tutorial esta en ingles.

http://java.sun.com/j2se/javadoc/writingdoccomments/index.html

Code Conventions for the JavaTM Programming Language

Las convenciones de código son importantes para los programadores por un número de razones:

• el 80% del coste del ciclo de vida de un software va al mantenimiento.
• Apenas cualquier software es mantenido por su vida entera por el autor original.
• Las convenciones de código mejoran la legibilidad del software, permitiendo entender el nuevo código más rápidamente y a fondo.
• Si usted envía su código fuente como producto, usted necesita cerciorarse de que también esté empaquetado y limpiao como cualquier otro producto que usted cree.

Nosotros utilizamos las convenciones de código para el lenguaje de programación de JavaTM:
http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html

Este Howto esta en ingles (el idioma oficial de la programación), no hay tradución por el momento, pero trata de cosas muy sencillas, pero que deben tomarse en cuenta a la hora de programar. Tales como:

• Nombres de archivos
• Organización de los archivos
• Identación del código
• Declaraciones
  
• Sentencias
• Comentarios
• Espacios en blancos
• Convencion de nombres
• Practicas de programación
• Ejemplos de código

Todos esto relacionado claro, con el formato que debe tener el código escrito por un equipo de programación.

Por suerte, existe una herramienta sencilla que automatiza este proceso (NO es que hagas de tu código un desatre :-D ). Jalopy es un formateador de código fuente para el lenguaje JAVA. El cual ayuda para tener una simetría (utilizando las conveción que definas) en tu código fuente. El cual comenzaré a utilizar en mis projectos.

http://jalopy.sourceforge.net/

Historia de Google

Los comienzos

Todo empezó en una primavera de 1995 cuando dos jóvenes universitarios, Sergey Brin, de 23 años, con experiencia en diseño web y titulado en Ingeniería Electrónica, y Larry Page, de 24, expero en tratamiento de datos y licenciado en Informática y Ciencias Matemáticas, que acabarian siendo cofundadores y actuales presidente y CEO de Google, se conocieron en un evento organizado por la Universidad de Standford para los aspirantes a su prestigioso Doctorado en Informática. Allí discutieron arduamente sobre cada tema hablando, sus sólidas opiniones y divergentes puntos de vista encontraron un objetivo común, conseguir información relevante de una gran cantidad de datos.

Es en otoño de ese mismo año, cuando estos dos estudiantes empiezan a desarrollar un algoritmo para la búsqueda de datos, que utilizarian en para el proyecto de "Biblioteca Digital" de la Universidad de Standford (Digital Library Project). En ese momento comenzó lo que más tarde sería llamado por Larry Page como PageRank, en 1997. También publicó, ese mismo año, un documento explicativo del PageRank que puedes encontrar aquí.

En enero de 1996, Larry y Sergey empezaron a desarrollar un motor de búsqueda llamado BackRub, nombrado así por su capacidad única de analizar los "enlaces entrantes" (enlaces que provienen de otras páginas) de una página web. Este buscador corría sobre varias máquinas Sun e Intel y su base de datos principal era guardada por un Sun Ultra II con 28Gb de disco y estaba implementado en Java y Python. Como curiosidad podemos ver un post de Larry preguntando una duda de Java (aquí). Larry, quien era conocido por haber construido una impresora a base de piezas de Lego, se puso manos a la obra para crear un nuevo entorno de servidores de gama baja (PC's), en vez de máquinas muy caras. Angustiados por su constante escasez de dinero, espereban siempre con ilusión la llegada de nuevas máquinas al departamento que pudieran utilizar para su proyecto. Muestra de esta escacez de medios son máquinas como esta.

Ya en 1997, BackRub pasa a convertirse en Google. Aún podemos ver como era Google por aquel entonces gracias a archive.org. El nombre "Google" es un juego de palabras que proviene de la palabra "googol", término acuñado por Milton Sirotta para referirse a a un número representado por un 1 seguido de 100 ceros. Un googol es un número muy largo. No existe un googol de nada en el universo, ni de estrellas, ni de partículas de polvo, ni de átomos. La utilización de este término por Google refleja la misión de organizar la inmensidad infinita que aparenta la world wide web.

Larry y Sergey continuaron perfeccionando su tecnología durante la primera mitad de 1998. Siguiente un camino que sería la clave del principio de Google, compraron un terabyte de discos a precios muy bajos y construyeron su propio data center en la habitación de Larry. Empezaron a buscar patrocinadores para su nueva empresa pero a pesar de la fiebre del puntocom de la época no tuvieron mucha suerte. Aquí podemos ver como era el diseño de Google por aquellos tiempos y aquí, el hardware que utilizaban.

Incapaces de interesar a ningún portal de los vigentes en aquel momento, Larry y Sergey deciden ir por su cuenta. Lo único que necesitaban era dejar de usar la habitación de Larry como datacenter, saldar sus deudas causadas por la compra de tantos discos y buscar a un inversor. Al final, además de los cien mil dólares ofrecidos por Andy Bechtolsheim, uno de los fundadores de Sun, consiguieron entre familia, amigos y otros parientes recaudar un capital inicial de almenos $1 millón de dólares.

A finales de Septiembre de 1998 Google Inc. es inauguarada en el garaje que les alquilaba un amigo. El local tenía grandes ventajas como una lavadora y una secadora entre otras cosas. También servía de parkin para el primer empleado de la compañía Craig Silverstein, ahora director de tecnología de Google.

Cuando Google.com aún estaba en fase beta, respondía a unas 10000 búsquedas al día. La premsa empezó a hacer eco de ello y varios artículos elogiando a Google aparecieron en USA Today y Le Monde. En diciembre de ese mismo año, PC Magazine nombró a Google en su top 100 de mejores buscadores del año 1998. Google empezaba a darse a conocer al mundo.

A partir de aquí Google empezó a crecer desmesuradamente. Al año siguiente, 1999, volvieron a mudarse a oficinas más grandes, con más empleados y respondiendo a alrededor de 500000 visitas. Y así hasta ahora, ganando premios, aportando calidad e innovación y batiendo records, Google es hoy el mejor buscador de la red y el más utilizado.

Soluciones

Espero que este metodo sea de mayor acceso y rapides para todos, mejorando la comunicación entre todos, puesto que permite la publicacion de comentarios desde nuestro (preferido) cliente de email. Tambien permite la publicaciones de fotos y cada comentario publicado puede llegar a tu cuenta de correo, todo esto sin tener que accesar a la página. Puedes rapidamente utilizar el boton de blogthis! de la barra de google si ves algo importante y quieres compartirlo.

Bienvenida

Bienvenidos al web logs de vnsjava