Este documento trata sobre herramientas auxiliares de programación como la documentación de código, el formato Javadoc y Doxygen para generar documentación, y el uso de Make para el mantenimiento de proyectos de software. En particular, describe cómo Javadoc y Doxygen permiten generar documentación a partir de comentarios en el código, y cómo Make automatiza el proceso de compilación mediante la especificación de tareas y dependencias.
Presentación inteligencia artificial en la actualidad
Ple Ut8
1. Programación en
Lenguajes Estructurados
U.T. 8: Programación avanzada
Herramientas auxiliares de programación
C.F.G.S. “Desarrollo de Aplicaciones Informáticas”
C.E.F.P. Juan de Colonia (Burgos)
Francisco Iglesias Villasol
David H. Martín Alonso
Serafina Martín Marcos
José Antonio Palma Escudero
- Curso 2005/2006 -
2. 2
Contenidos
1.- Documentación: Finalidad
2.- Documentación: Etapas
3.- Documentación de código
4.- Documentación de interfaz
5.- El formato quot;Javadocquot;
– Sintaxis
– Doxygen
– Reglas de estilo
– Etiquetas de código
6.- Herramientas de mantenimiento (make)
– Otras herramientas
7.- Vulnerabilidades y seguridad
8.- Referencias
9.- Licencia
ple-ut8 v1.0.odp C.E.F.P. Juan de Colonia - Programación en Lenguajes Estructurados 02/07/2006
3. 3
U.T. 8: Programación avanzada
Documentación de código
– Javadoc
– Doxygen
ple-ut8 v1.0.odp C.E.F.P. Juan de Colonia - Programación en Lenguajes Estructurados 02/07/2006
4. 4
Documentación: Finalidad
Finalidad de la documentación
Intercambio de conocimiento acerca de la aplicación y su desarrollo
Aprovechamiento óptimo de la funcionalidad programada
Calidad → Reducción de costes
Costes de desarrollo
– Adecuación a las especificaciones
– Reutilización de código
– Reducción de errores
– Reducción del esfuerzo de reparación
– Reducción del esfuerzo de adaptación y mejora
Costes de explotación
– Tiempo de aprendizaje
– Uso eficiente
– Reducción de errores de uso
Supone un coste inicial amortizado inmediatamente
ple-ut8 v1.0.odp C.E.F.P. Juan de Colonia - Programación en Lenguajes Estructurados 02/07/2006
5. 5
Documentación: Etapas
Distintas metodologías de desarrollo concretan distintos modelos
Análisis y desarrollo
Organigramas, ordinogramas, pseudocódigo. (Prog. estructurada)
UML (Prog. Orientada a Objetos)
Diagramas entidad-relación (Bases de Datos)
Codificación
Paradigmas: modular, estructurado, orientado a objetos
Identificadores
Comentarios en línea (aclaración del algoritmo)
Comentarios formales (ficheros, clases, funciones, parámetros)
Puesta en producción
Manual de usuario
Manual de administrador
Manual de programador
ple-ut8 v1.0.odp C.E.F.P. Juan de Colonia - Programación en Lenguajes Estructurados 02/07/2006
6. 6
Documentación de código
La falta de claridad en el código limita seriamente el desarrollo
El esfuerzo de programación crece exponencialmente
La programación estructurada emplea patrones conocidos
Fácil comprensión
Fácil adaptación
Importancia de espaciado y sangrado
Los identificadores facilitan la lectura y la comprensión
Nombres significativos
Importancia de evitar nombres crípticos
Diferentes convenios asociados históricamente con cada lenguaje
Comentarios intercalados
Para explicar procesos complicados
NO sustituyen ni a la claridad, ni a la sencillez ni a los identificadores
ple-ut8 v1.0.odp C.E.F.P. Juan de Colonia - Programación en Lenguajes Estructurados 02/07/2006
7. 7
Documentación de interfaz
Comentarios a nivel de módulos
Funciones, ficheros, clases. Identifican el módulo.
Informan de su funcionalidad y condiciones de uso (interfaz)
Simultáneos a la codificación
– Ayuda del propio programador
– Perdida de utilidad y de contenido si se hacen en diferido.
Formatos predeterminados
Establecidos por la organización o comunidad de programadores
Propuestos por el lenguaje en lenguajes OO como Java o C# (.NET)
Determinados por las herramientas
Generadores de documentación
Generación automática en formatos múltiples
A partir de los comentarios en el propio código
ple-ut8 v1.0.odp C.E.F.P. Juan de Colonia - Programación en Lenguajes Estructurados 02/07/2006
8. 8
El formato “Javadoc” (I)
Java: lenguaje de programación orientado a objetos
Origen 1990 (Sun Microsystems)
Inspirado en C y C++
Interpretado, multiplataforma
Lenguaje de propósito general muy popular y referente en POO
Javadoc: Herramienta de generación de documentación para Java
Parte del entorno de desarrollo básico (Java Development Kit, JDK)
A partir de comentarios en el código genera HTML (páginas web)
Uniformidad de estilo de TODA la documentación de Java
Mecanismo de comunicación universal → Reutilización
Objetivo: documentar elementos reutilizables
Paquetes, clases, métodos, parámetros, atributos
Documentación de la interfaz para poder reutilizar clases
ple-ut8 v1.0.odp C.E.F.P. Juan de Colonia - Programación en Lenguajes Estructurados 02/07/2006
9. 9
El formato “Javadoc” (II)
Compatible C, pero con dos **
/** Punto en un espacio 2D.
* @author <a href=quot;mailto:profe@cesburquot;>Profe de PLE</a>
*/ Identificación Formatos HTML
public class Punto {
Hiperenlaces a código
/** Crea un {@link Punto} a partir de sus coordenadas.
* @param cartesianas true para cartesianas, false para angulares
* @param a abscisa o módulo
* @param b ordenada o argumento
*/
public Punto(boolean cartesianas, double a, double b) {
...
} Descripción de la funcionalidad
Palabras clave, con @
/** Realiza un desplazamiento horizontal.
* @param dx desplazamiento Parámetros necesarios
* @return la abscisa tras el desplazamiento
*/ Resultados
public void moverx(double dx) {
...
return x;
}
ple-ut8 v1.0.odp C.E.F.P. Juan de Colonia - Programación en Lenguajes Estructurados 02/07/2006
10. 10
Doxygen
Generador de documentación con licencia libre GPL de GNU
Multiplataforma: GNU/Linux, MAC OS X, MS Windows
Aplicable a C, C++, Java, C#, PHP, Python y alguno más
Compatible con Javadoc, aunque requiera algún ajuste para C
Genera ficheros HTML, pero también RTF y LATEX
Operación:
Descarga e instalación
– En Linux está disponible en las distribuciones habituales
– DOS: Descargar, descomprimir y agregar al PATH. También hay instalador.
En el directorio de código fuente crear el fichero de configuración
– doxygen -g → Doxyfile
– Recomendable crear directorios separados: src, bin y docs
Editar el fichero Doxyfile a gusto con un editor de texto
Ejecutando nuevamente “doxygen” se generan los documentos
– Genera avisos de código no documentado
ple-ut8 v1.0.odp C.E.F.P. Juan de Colonia - Programación en Lenguajes Estructurados 02/07/2006
11. 11
Doxyfile
PROJECT_NAME = quot;PLE-UT8quot;
PROJECT_NUMBER = 1.0
OUTPUT_DIRECTORY = ../docs
OUTPUT_LANGUAGE = Spanish
ALWAYS_DETAILED_SEC = YES
JAVADOC_AUTOBRIEF = YES
DETAILS_AT_TOP = YES
OPTIMIZE_OUTPUT_FOR_C = YES
RECURSIVE = YES
SOURCE_BROWSER = YES
ALPHABETICAL_INDEX = YES
No genera nada hasta que no se documentan los ficheros
Etiqueta @file al frente de los ficheros deseados
Descripción de funciones incluyendo @param y @return
ple-ut8 v1.0.odp C.E.F.P. Juan de Colonia - Programación en Lenguajes Estructurados 02/07/2006
12. 12
Ejemplo: buffer.h
/** @file buffer.h Función para concatenar cadenas */
/**
* Tamaño de buffer empleado.
*/
#define TAMBUF 1024
/** Mantiene una cadena de texto a la que se puede agregar otras
* cadenas. En caso de que el tamaño sobrepase el valor de
* {@link #TAMBUF} la cadena total queda truncada, pero correctamente
* terminada (con un cero).
* @param texto una cadena de texto o NULL para inicializar
* @return la cadena completa
*/
const char *meteBuffer (const char *texto);
ple-ut8 v1.0.odp C.E.F.P. Juan de Colonia - Programación en Lenguajes Estructurados 02/07/2006
13. 13
Reglas de estilo
Nuestro objetivo es documentar la funcionalidad de las funciones
Texto concreto y conciso
Tratar de no calcar el identificador, sino darle más sentido
No repetir: “Función que..”
Comienzan con un verbo en tercera persona de singular
La primera frase se emplea en los índices: ser muy concretos
– Hasta el primer punto '.' y espacio (para no cortar direcciones de correo)
– Podemos ampliar la explicación en oraciones sucesivas, pero teniendo en
cuenta que tampoco se busca explicar aquí el algoritmo: el código debe ser
autoexplicativo.
Indicar los comportamientos excepcionales y errores tratados
ple-ut8 v1.0.odp C.E.F.P. Juan de Colonia - Programación en Lenguajes Estructurados 02/07/2006
14. 14
Etiquetas Javadoc / Doxygen
Delimitación de comentarios: /** */
Descripciones: texto. Permiten HTML básico para formato.
Parámetros de funciones: @param identificador
Valor devuelto: @return (sin identificador)
Enlaces internos:
En bloque: @see funcion() / @see #identificador
En línea: {@link funcion()} / {@link #identificador}
– Entre llaves; se pueden intercalar en cualquier texto
Identificación: @author nombre / @version numero
Ficheros (en Doxygen): @file nombre.ext Contenido
ple-ut8 v1.0.odp C.E.F.P. Juan de Colonia - Programación en Lenguajes Estructurados 02/07/2006
15. 15
U.T. 8: Programación avanzada
Mantenimiento de proyectos
– Make
– Otras herramientas
ple-ut8 v1.0.odp C.E.F.P. Juan de Colonia - Programación en Lenguajes Estructurados 02/07/2006
16. Mantenimiento de proyectos: 16
make
La compilación de proyectos se torna compleja
Gran número de ficheros implicados
Opciones de compilación
Diferencias de compilación entre sistemas heterogéneos
Posibilidad de compilación parcial de los elementos actualizados
Solución: Mantenimiento externo de datos de compilación
Archivos de opciones adicionales, distribuidos junto al código
Estándar de facto para C: make
Entornos gráficos de desarrollo: modelos particulares
– Complejidad adicional, particular del entorno
Make: Herramienta de gestión y mantenimiento de programas
Descripción de cada proyecto: Archivos Makefile propios
Colección de tareas subordinadas
Admite macros para referencias repetibles
ple-ut8 v1.0.odp C.E.F.P. Juan de Colonia - Programación en Lenguajes Estructurados 02/07/2006
17. 17
Ejemplo: Makefile
Tareas/dependencias/instrucciones
– Antes de cada tarea se revisan las tareas de las que depende
– Sólo ejecuta la tarea si está desactualizada respecto a las dependencias
OBJS = modulo1.o modulo2.o
FICH = modulo1.c modulo2.c cabecero.h Makefile
miprograma: $(OBJS) Tarea: dependencias
→ instrucciones
gcc -o miprograma modulo1.o modulo2.o
modulo1.o: modulo1.c cabecero.h gcc -c: Compilar, pero no enlazar
gcc -Wall -c modulo1.c (ficheros objeto con extensión .o)
modulo2.o: modulo2.c cabecero.h Dependencias: Sólo compilar
gcc -Wall -c modulo2.c si x.c o x.h han cambiado
clean borrar:
rm -f $(OBJS) PLE> make
...
PLE> make borrar
zip comprimir: ...
zip miprograma.zip $(FICH) PLE> _
ple-ut8 v1.0.odp C.E.F.P. Juan de Colonia - Programación en Lenguajes Estructurados 02/07/2006
18. 18
Otras herramientas
Autoconf y automake
Rizando el rizo: Generación automática del Makefile
Diagnóstico del sistema, herramientas y/o librerías disponibles
A partir de plantillas Makefile.in
Se incluyen scripts para el usuario: configure, setup, etc.
CVS, Subversion [MC]
Sistemas centralizados en red de control de versiones
Recoge las actualizaciones de código de todos los programadores
Control de acceso de los usuarios por zonas
Controla incompatibilidades
Permite ramificaciones, congelaciones, reversiones, etc
Permite acceso histórico (versión del día tal, a tal hora)
Integrado, accesible en entornos de desarrollo
ple-ut8 v1.0.odp C.E.F.P. Juan de Colonia - Programación en Lenguajes Estructurados 02/07/2006
19. 19
Otras herramientas (II)
Depuradores
Ejecución de programas en entornos controlables
Ejecución paso a paso, puntos de parada condicional
Monitorización del estado de las variables
Análisis post-mortem de volcados de memoria de programas acabados
Requieren una compilación diferenciada
– Genera ejecutables ampliados, de mayor tamaño
Integrados en entornos de desarrollo
Refactorizaciones
Herramientas que modifican el código fuente sin alterar su función
Mejora del código
– Redenominación de identificadores
– Extracción de variables y subprogramas
– Reordenación de elementos en el código fuente
ple-ut8 v1.0.odp C.E.F.P. Juan de Colonia - Programación en Lenguajes Estructurados 02/07/2006
20. 20
Otras herramientas (III)
Métricas
Análisis de código fuente: Indicadores de calidad
Aspectos, patrones, plantillas, componentes
Modelos de código adaptables para ciertas situaciones
Facilitan la generación automática de código
ple-ut8 v1.0.odp C.E.F.P. Juan de Colonia - Programación en Lenguajes Estructurados 02/07/2006
21. 21
U.T. 8: Programación avanzada
Vulnerabilidades
ple-ut8 v1.0.odp C.E.F.P. Juan de Colonia - Programación en Lenguajes Estructurados 02/07/2006
22. Efecto de los fallos 22
del programador
Los errores de programación no sólo afectan a la funcionalidad
esperada del programa sino que pueden comprometer a terceros y
poner en peligro la seguridad de todo el sistema.
La seguridad es prioritaria sobre el rendimiento del programa
Un pequeño error escondido, puesto en Internet, deja de ser pequeño
No podemos suponer que el usuario siga las instrucciones dadas
– Los atacantes, al contrario, tratarán de forzar las entradas y sacar provecho
Consecuencias
Destrucción del sistema
Pérdida de información o revelación de información clasificada
Denegación de servicio, imposibilidad de acceso
Ataque indirecto a otros sistemas
Soluciones combinadas: programación + sistemas + recuperación
Medidas proactivas (previsión) y reactivas (reacción)
ple-ut8 v1.0.odp C.E.F.P. Juan de Colonia - Programación en Lenguajes Estructurados 02/07/2006
23. Guía de buenos hábitos 23
del programador
Simplicidad del código (= modularidad, programación estructurada)
Vigilancia del uso de memoria evitando desbordamientos
– Uso de funciones de librería con límite de búffer
Vigilancia de las entradas de usuario
– Evitar reintento de entradas fallidas → Denegaciones de servicio
Vigilancia de los accesos a disco
– Bloqueando los ficheros se puede bloquear el programa
– Los ficheros temporales pueden ser muy vulnerables
Registro de operaciones
– Permite investigar ataques sufridos: origen y alcance
– Puede facilitar la recuperación de datos
Lecturas
– Los hácker son los primeros en leer los foros de seguridad
Otro: está lista siempre estará incompleta, siempre faltará uno...
ple-ut8 v1.0.odp C.E.F.P. Juan de Colonia - Programación en Lenguajes Estructurados 02/07/2006
24. 24
Referencias
Doxygen Manual. [DOXMAN]
Patricio Salinas C. <psalinas@dcc.uchile.cl>
http://www.stack.nl/~dimitri/doxygen/manual.html
How to Write Doc Comments for the Javadoc Tool. [JDTUT]
Sun Microsystems <JavadocTool@sun.com>
http://java.sun.com/j2se/javadoc/writingdoccomments/
Midnight Commander - CVS Repositories. [MC]
GNU - Free Software Foundation
http://cvs.savannah.gnu.org/viewcvs/?root=mc
ple-ut8 v1.0.odp C.E.F.P. Juan de Colonia - Programación en Lenguajes Estructurados 02/07/2006
25. 25
Licencia de uso
Este material está disponible bajo una Licencia Creative Commons,
http://creativecommons.org/licenses/by-nc-sa/2.5/es/
ple-ut8 v1.0.odp C.E.F.P. Juan de Colonia - Programación en Lenguajes Estructurados 02/07/2006