Doc.SEmenario
Páginas: 5 (1196 palabras)
Publicado: 2 de abril de 2013
Documentación en JAVA
La apropiada documentación, junto con el buen estilo de programación, contribuye a la correcta presentación del código. Ésta última es necesaria por una serie de razones, una de las cuales es la creciente aceptación del modelo de software abierto, donde el código es parte del producto que se ofrece.
La función de la documentación es permitir a cualquier lector que seafamiliar con el lenguaje entender rápidamente el funcionamiento del programa. De ser necesario, hasta el grado de que sea capaz de extraer partes del mismo y insertarlas en otro código si lo considera prudente.
En JAVA, se manejan una serie de reglas distintas a las del pseudo-lenguaje. Si bien el principio para documentar es el mismo (inclusión de formalizaciones y aserciones con el objeto declarificar), se producen algunas diferencias, en parte por las limitaciones del lenguaje.
Toda documentación JAVA debe hacerse mediante comentarios, limitados por los marcadores /* y */ . Recuerde además que, por convención, la primera de un comentario de varias líneas debe estar vacía.
Para iniciar, todo archivo debe poseer un encabezado. Si el archivo contiene una única clase, dichoencabezado se referirá a ella. Si por el contrario, contiene varias (como ocurre cuando hay clases privadas), entonces cada clase deberá tener su encabezado.
El encabezado del Archivo debe indicar:
• Nombre del archivo
• Descripción, lo cual puede ser el propósito de las clases contenidas en él
• Autor(es). De preferencia debe incluirse un medio de contacto, como puede ser una dirección de correoelectrónico.
• Versión. Esto es muy útil cuando se comparten e intercambian copias de un mismo archivo entre varias personas. La primera versión totalmente implementada recibe el número 1.0. Debe incluirse fecha y hora de la última modificación.
El bloque de comentario que contenga esta información debe estar al inicio del archivo, antes de la primera línea de código.
Deben documentarseigualmente las variables utilizadas, especialmente aquéllas que tengan validez a todo lo largo de la clase, como constantes y variables globales. Usualmente basta con una línea de comentario indicando el uso que se da a la variable.
Aquí debe evitarse la sobre documentación. Si una variable tiene alcance limitado (funciones de cota de iteraciones, variables internas de procedimientos) y se consideraque su propósito queda claro en el código (los nombres mnemónicos ayudan), entonces puede omitirse su documentación.
De manera similar al pseudolenguaje, deben hacerse aserciones respecto al estado de las variables, lo cual incluye precondiciones, postcondiciones, invariantes de los ciclos, etc.
Note que las aserciones deben hacerse en el momento adecuado. Las precondiciones sólo tienen sentidouna vez que se hayan leído los valores de las variables y se haya realizado el chequeo. Igualmente es conveniente indicar las postcondiciones y estados intermedios inmediatamente después de que se hagan ciertos.
En el caso de los ciclos anidados, si éstos están intrínsecamente relacionados hasta grado de que sus invariantes sean casi iguales, puede documentarse sólo la más descriptiva de ellas(generalmente la más interna). Para hacer esto debe asegurarse de que todas las invariantes omitidas pueden deducirse completamente de la mostrada. Sin embargo, conviene mostrar la función de cota de todos los ciclos.
Los comentarios deben estar indentados al mismo nivel que el trozo de código al que se refieren.
Por último, y posiblemente más importante, deben documentarse todos los métodos dela clase. La documentación del método debería permitir al lector utilizar el método y predecir su comportamiento sin tener que leer el cuerpo del mismo.
La documentación del método debe contener:
Nombre: Indicación de si es procedimiento o función, y el nombre mediante el cual es llamado.
Objetivo: Una breve oración en lenguaje natural describiendo para qué sirve el método. Trate de ser...
La apropiada documentación, junto con el buen estilo de programación, contribuye a la correcta presentación del código. Ésta última es necesaria por una serie de razones, una de las cuales es la creciente aceptación del modelo de software abierto, donde el código es parte del producto que se ofrece.
La función de la documentación es permitir a cualquier lector que seafamiliar con el lenguaje entender rápidamente el funcionamiento del programa. De ser necesario, hasta el grado de que sea capaz de extraer partes del mismo y insertarlas en otro código si lo considera prudente.
En JAVA, se manejan una serie de reglas distintas a las del pseudo-lenguaje. Si bien el principio para documentar es el mismo (inclusión de formalizaciones y aserciones con el objeto declarificar), se producen algunas diferencias, en parte por las limitaciones del lenguaje.
Toda documentación JAVA debe hacerse mediante comentarios, limitados por los marcadores /* y */ . Recuerde además que, por convención, la primera de un comentario de varias líneas debe estar vacía.
Para iniciar, todo archivo debe poseer un encabezado. Si el archivo contiene una única clase, dichoencabezado se referirá a ella. Si por el contrario, contiene varias (como ocurre cuando hay clases privadas), entonces cada clase deberá tener su encabezado.
El encabezado del Archivo debe indicar:
• Nombre del archivo
• Descripción, lo cual puede ser el propósito de las clases contenidas en él
• Autor(es). De preferencia debe incluirse un medio de contacto, como puede ser una dirección de correoelectrónico.
• Versión. Esto es muy útil cuando se comparten e intercambian copias de un mismo archivo entre varias personas. La primera versión totalmente implementada recibe el número 1.0. Debe incluirse fecha y hora de la última modificación.
El bloque de comentario que contenga esta información debe estar al inicio del archivo, antes de la primera línea de código.
Deben documentarseigualmente las variables utilizadas, especialmente aquéllas que tengan validez a todo lo largo de la clase, como constantes y variables globales. Usualmente basta con una línea de comentario indicando el uso que se da a la variable.
Aquí debe evitarse la sobre documentación. Si una variable tiene alcance limitado (funciones de cota de iteraciones, variables internas de procedimientos) y se consideraque su propósito queda claro en el código (los nombres mnemónicos ayudan), entonces puede omitirse su documentación.
De manera similar al pseudolenguaje, deben hacerse aserciones respecto al estado de las variables, lo cual incluye precondiciones, postcondiciones, invariantes de los ciclos, etc.
Note que las aserciones deben hacerse en el momento adecuado. Las precondiciones sólo tienen sentidouna vez que se hayan leído los valores de las variables y se haya realizado el chequeo. Igualmente es conveniente indicar las postcondiciones y estados intermedios inmediatamente después de que se hagan ciertos.
En el caso de los ciclos anidados, si éstos están intrínsecamente relacionados hasta grado de que sus invariantes sean casi iguales, puede documentarse sólo la más descriptiva de ellas(generalmente la más interna). Para hacer esto debe asegurarse de que todas las invariantes omitidas pueden deducirse completamente de la mostrada. Sin embargo, conviene mostrar la función de cota de todos los ciclos.
Los comentarios deben estar indentados al mismo nivel que el trozo de código al que se refieren.
Por último, y posiblemente más importante, deben documentarse todos los métodos dela clase. La documentación del método debería permitir al lector utilizar el método y predecir su comportamiento sin tener que leer el cuerpo del mismo.
La documentación del método debe contener:
Nombre: Indicación de si es procedimiento o función, y el nombre mediante el cual es llamado.
Objetivo: Una breve oración en lenguaje natural describiendo para qué sirve el método. Trate de ser...
Leer documento completo
Regístrate para leer el documento completo.