Documentacin de Codigo

Qu hay que documentar?

Hay que aadir explicaciones a todo lo que no es evidente. No hay que repetir lo que se hace, sino
explicar por qu se hace. Y eso se traduce en:
* de qu se encarga una clase? un paquete?
* qu hace un todo?
* cu!l es el uso esperado de un todo?
* para qu se usa una varia"le?
* cu!l es el uso esperado de una varia"le?
* qu algorito estaos usando? de d#nde lo heos sacado?
* qu liitaciones tiene el algorito? ... la ipleentaci#n?
* qu se de"er$a e%orar ... si hu"iera tiepo?
Cundo hay que poner un comentario?
&or o"ligaci#n '%avadoc(:
* al principio de cada clase
* al principio de cada todo
* ante cada varia"le de clase
&or conveniencia 'una l$nea(:
* al principio de )ragento de c#digo no evidente
* a lo largo de los "ucles
Y por si acaso 'una l$nea(:
* siepre que hagaos algo raro
* siepre que el c#digo no sea evidente
*s decir, que los coentarios !s vale que so"ren que que )alten.
Nota: cuando un programa se modifica, los comentarios deben modificarse al tiempo, no sea que los
comentarios acaben refirindose a algo que ya no utilizamos.
+on eclipse podeos utili,ar los coentarios tipo -as. para de)inir tareas pendientes o correcciones
necesarias
//-010 tareas necesarias por ipleentar pero que por alguna ra,on no pudios ipleentar
//2345* tareas que es necesaria darle una revisi#n o solicitar apoyo para que otro prograador
lo revise y nos de los coentarios
CONVECIONES PARA LA DOCUMENTACION.
clases e interfaces
0"ligatorias:
6author 7 no"re del autor
6version 7 identi)icaci#n de la versi#n y )echa
0pcional:
6see 7 re)erencia a otras clases y todos
constructores y mtodos
0"ligatorias:
6para 7 una por arguento de entrada
6return 7 si el todo no es void
6exception # 6thro8s 7 una por tipo de *xception que se puede lan,ar
'6exception y 6thro8s se pueden usar indistintaente(.
campos y variables
Ninguna etiqueta es o"ligatoria.
CONVECIONES DE NOMBRES DE VARIABLES.
*s recoenda"le que adopteos un estilo para la codi)icaci#n, aqui listo algunas convenciones
o"ligatorias para de)inir los no"re de las varia"les, etodos o clases:
-odas los no"re de varia"les, etodos, constantes, )inales, clases, etc, etc... tienen que ser en
3N9:*; y si es necesario especi)icar que hace o a que se re)iere sera necesario de)inirlo con un
coentario.
<tili,ar no"res descriptivos para las clases, evitando los no"res uy largos.
&ara los no"res de clases poner la priera letra en ay=sculas y las de!s en in=sculas. &or
e%eplo: *ployee
+lases: ;i el no"re tiene varias pala"ras ponerlas todas %untas 'sin separar con 7 o >( y poner la
priera letra de cada pala"ra en ay=sculas. &or e%eplo: *ployee?oles.
5etodos y @ari"ales: ;eguir la isa nora, pero con la priera letra de la priera pala"ra en
in=sculas. &or e%eplo: sho8?ecords.
+onstantes o @aria"les 2inales: &ara las constantes 'datos con el odi)icador )inal( usar
no"res en ay=sculas, separando las pala"ras con >