Buenas a todos,
Hoy creo que voy a sorprender a todo el mundo con uno (post) de los más, si no el más, tonto de este foro. La pregunta que quería hacer es...
Vosotros como comentais en vuestros programas? es que se me hacen feos mis comentarios al estilo:
/*
* Class user
* @Author: Neb1 Post Chorras
* @Description: ...
* ....
*/
Ale, abro paraguas xD
Pues dependiendo del lenguaje que use...
-Javadoc (tu ejemplo) para Java.
-Doxygen para C++/PHP.
-XML para C#.
Si es una linea "//", si son varias, uso lo mismo que tú exactamente igual espaciado xD
#4 lol acabo de leerme bien #2 y estoy como tú XD
#2 te puedes creer que no tenía ni idea de que existian utilidades para generar la documentación, y que yo ni siquiera sabía que eso era javadoc? simplemente había copiado formas que había visto en diversas APIS.
No me esperaba aprender tanto en un post que creía tenía tan poca chicha, muchas gracias, eres un crack!
Pd: no hay un plugin para notepad++ de javadoc o doxygen??
Pd: Me acabo de bajar el doxygen. No era lo que me esperaba, creía que era para hacer comentarios al vuelo, pero esto parece más enfocado a crear la documentación tras finalizar el proyecto :S
En Eclipse, si encima de una clase o un método escribes /* y le das a enter, te crea la estructura javadoc solo 
Yo para comentarios de clases y métodos uso javadoc, y dentro de los métodos, para ir comentando el proceso, voy explicando con // 
lo hago como #2
Y cualquier lenguaje que no tenga generación de documentación propia uso siempre doxygen.
// Así si es una línea
/Así
si son
varias lineas/
//////////////////////////////////////////////////////////////
/////////////// TÍTULO IMPORTANTE ////////////////////
//////////////////////////////////////////////////////////////
Yo en Java los hago con Javadoc.
/**
* Descripción del método.
* @author yo
* @param parametro
* @return lo que devuelve el método
* @throws la excepcion
*/
Esto me lo "obligo" porque tengo el plugin Checkstyle para Eclipse
#4, todo lo que he listado son metodos para generar manuales a partir del codigo; la cosa esta en que de todos ellos, Javadoc es el mas "simple" para que te permita ver sin demasiado engorro la referencia desde el propio codigo, sin tener que compilar y generar el manual (Doxygen y XML añaden demasiadas palabras clave para verlo claro "al vuelo").
Dependiendo del IDE que uses, puede que te cree la ayuda al vuelo; si bien tanto Javadoc en Eclipse/Netbeans como XML en Visual Studio se pueden compilar en un manual HTML una vez lo has documentado todo bien, los propios IDEs te van generando una cache al vuelo que te muestran en el autocompletion/IntelliSense. Doxygen digamos que es mas "monolitico", se emplea para crear manuales estaticos de codigo finalizado. No se si existen plugins de IDEs que te parsean Doxygen al vuelo y te lo añaden al autocompletion.
Hablando de comentarios... ¿seguís alguna guía de estilo particular? Yo hoy me he encontrado con esta de Google, y como todo el mundo sabe, si es de Google, es buena.
http://code.google.com/p/google-styleguide/
Tiene para C++ (extrapolable a lenguajes descendientes), Objective-C, python y diseño de formatos en XML. Y un fichero de configuración para Emacs, que ayuda con el de C++.
Neb1 como veo que usas mucho php, te recomendaría usar phpDocumentor. Genera una muy buena documentación a partir de los comentarios, aunque lo mismo ya lo conocías
Echale un vistazo ya que como los comentarios los usamos a menudo para dar claridad al código pues ya de paso que nos sirva para tener una documentación al estilo javadoc de java.
Creo que la documentación existente en la página de PEAR utiliza phpDocumentor (o alguno similar) para la documentación que tiene.