Unidad I "Conceptos bsicos y herramientas de

programacin"

1.7 Documentacin y estilos para escribir cdigo
1
Departamento de Ciencias e Ingeniera de la Computacin
Academia de Ciencias de la Computacin
Contenido
Software
Ingeniera del software
Ciclo de vida del software
Documentacin de software
Documentacin externa
Documentacin interna
Cdigo autodocumentado
Comentarios efectivos
Tcnicas para comentar cdigo




2
Software
Comnmente se asocia el termino Software se
asocia con Programa de computadora. Sin embrago
una definicin ms adecuada dentro del contexto
de la ingeniera en sistemas computacionales sera:

Programa de computadora y la documentacin
asociada a este. [Ian Sommerville, 2005]

Nota: Los productos de software se pueden
desarrollarse para algn cliente en particular o para
un mercado general.




3
Ingeniera del software
La ingeniera del software es un disciplina de
ingeniera que comprende todos los aspectos de la
produccin de software.

Cul es la diferencia entre ingeniera de software
y ciencia de la computacin?
La ciencia de la computacin comprende la teora y
los fundamentos; la ingeniera de software
comprende las formas practicas para desarrollar y
entregar un software til.





4
Cul es la diferencia entre ingeniera de software
e ingeniera de sistemas?
La ingeniera de sistemas se refiere a todos los
aspectos del desarrollo de sistemas informticos,
incluyendo hardware, software e ingeniera de
procesos. La ingeniera de software es parte de este
proceso





5
Ciclo de vida del software
6
Definicin de necesidades
Los clientes e ingenieros definen el software a
producir y las restricciones de su operacin.

Se solicitan y recopilan los requerimientos y
necesidades a satisfacer.






7
Anlisis
Con base en las necesidades considerar
restricciones, flujo y procesamiento de la
informacin as como las arquitecturas y tecnologas
ms adecuadas para su construccin.







8
Diseo
Construccin del sistema en papel, incluyendo toda
la documentacin y representaciones graficas
necesarias para construir el software por un equipo
de trabajo.







9
Codificacin
Implementar el diseo apoyndose de las
herramientas de programacin necesarias.
Es importante que conforme la codificacin va
avanzando, se documente en el la relacin
codificacin-diseo.







10
Pruebas
Las pruebas de software, son los procesos que
permiten verificar y revelar la calidad de un
producto software. Son utilizadas para identificar
posibles fallos de implementacin, calidad, o
usabilidad de un programa.




11
Validacin
Las pruebas de validacin en la ingeniera de
software son el proceso de revisin que el sistema
de software producido cumple con las
especificaciones y que cumple su cometido. Es
normalmente una parte del proceso de pruebas de
software de un proyecto, que tambin utiliza
tcnicas tales como evaluaciones, inspecciones, y
tutoriales. La validacin es el proceso de comprobar
lo que se ha especificado es lo que el usuario
realmente quera.



12
Mantenimiento y evolucin
El mantenimiento del software contempla la
modificacin de un producto de software despus
de la entrega para corregir averas, para mejorar
funcionamiento u otras cualidades, o para adaptar
el producto a nuevas utilidades y funciones.

Mantenimiento correctivo: La modificacin reactiva
de un producto de software se realiz despus de
entrega para corregir problemas descubiertos.
13
Mantenimiento adaptante: La modificacin de un
producto de software se realiz despus de entrega
para mantener un producto de software usable un
ambiente cambiante o que cambiaba.

Mantenimiento de perfectivo: Modificacin de un
producto de software despus de la entrega para
mejorar funcionamiento o capacidad de
mantenimiento.

Mantenimiento preventivo: Modificacin de un
producto de software despus de que entrega para
detectar y para corregir averas latentes en el
producto de software antes de que se conviertan en
averas eficaces.



14
Documentacin del software
Aunque muchas veces es omitida por los
principiantes y los que se dedican a producir
resultados rpidos debido a que no es tan atractiva
como la codificacin, la documentacin --al igual
que el diseo-- es una marca del orgullo profesional
que el programador pone en sus creaciones.

Existen dos clases de documentacin:
Documentacin externa
Documentacin interna


15
Documentacin Externa
En esta categora estn no slo los ms visibles para los
usuarios tales como los manuales de operacin y de
instalacin del software, sino tambin los documentos
de diseo utilizados durante el desarrollo del software:
copia de los requerimientos, copia del algoritmo
empleado as como de las alternativas consideradas,
diagramas de flujo, copia de los documentos que se
utilizan para el diseo de las entradas y salidas visuales
o impresas, copia de los estndares de desarrollo,
listado ms actual del cdigo fuente, documentos
relacionados con las modificaciones hechas al proyecto,
as como notas importantes de diseo usadas por los
desarrolladores durante el diseo y la implementacin,
entre otras.
16
Documentacin Interna
A diferencia de la documentacin externa, la
documentacin interna se encuentra dentro del cdigo
mismo y es la ms detallada de las dos. Puesto que es la
ms cercana al cdigo, la documentacin interna es la
que se suele mantener ms actualizada y correcta a
medida que el cdigo se modifica.

La documentacin interna es muy importante puesto
que facilita grandemente la lectura y comprensin del
cdigo, tanto para el propio programador como para
todos los que necesiten leerlo, y es especialmente til en
las fases de prueba y mantenimiento de los programas.
17
Es importante la relacin que se mantenga entre la
documentacin interna con el diseo y parte de la
documentacin externa.

El principal contribuyente de la documentacin a
nivel de cdigo no son los comentarios, sino el buen
estilo de programacin, el cual incluye una buena
estructura de programa, el uso de un acercamiento
directo y fcilmente comprensible, buenos nombres
de variables y de rutinas, uso de constantes
nombradas en lugar de valores literales, un
esquema claro y la minimizacin de la complejidad
del control de flujo y de las estructuras de datos.
18
El cdigo de los programas escritos con un estilo
pobre de programacin casi siempre es crptico.

An cuando se le trate de explicar usando
comentarios, su calidad no se ve mejorada:
permanece oscuro, difcil de leer y de modificar.

La nica manera de clarificarlo es rescribindolo
usando un mejor estilo de programacin.

De este modo el cdigo ser ms legible, an si no
posee comentarios que lo expliquen.
19
El cdigo que es legible por s solo se denomina
cdigo autodocumentado, y es una caracterstica
deseable para cualquier programa de software.

Tal cdigo descansa en el buen estilo de
programacin utilizado en su creacin para
sobrellevar la mayor parte de la documentacin
interna.

En un cdigo bien escrito, los comentarios son
piezas de informacin realmente necesarias que
complementan la legibilidad y no una carga extra
que, aunque de utilidad, hace que se incremente el
tamao del cdigo fuente.
20
Cdigo autodocumentado
Si al escribir el cdigo se cumple con los siguientes
cuestionamientos, es posible indicar que un cdigo
en C es autoexplicativo.
Funciones
El nombre describe exactamente lo que hace?

Desempea una procedimiento o funcin bien
definido?

Las variables y datos estructurados de cada funcin
corresponden a dicha funcin?

Es obvio y claro el prototipo de cada funcin?





21
Variables
Los nombres son lo suficientemente descriptivos?

Son las variables usadas nicamente para el
propsito para el cual fueron nombradas?

Se utilizan constantes nombradas en lugar de
constantes literales?

La convencin de nombres de identificadores
empleada distingue entre los nombres de tipos de
datos, los tipos enumerados, las constantes
nombradas, las variables locales y las variables
globales?



22
Flujo del programa
Es claro el flujo de ejecucin a travs del cdigo?

Estn las sentencias de cdigo relacionadas
agrupadas o cercanas entre s?

Son las estructuras de control lo suficientemente
simples, tal que minimizan la complejidad?

Cada ciclo desempea una y solo una funcin, como
debera hacerlo una rutina bien diseada?

Se ha minimizado el anidamiento (de ciclos y rutinas
por ejemplo)?
23
Comentarios efectivos
Los comentarios errneos al cdigo pueden
confundir a sus lectores, incluso si el cdigo se ha
escrito usando un buen estilo de programacin. El
cdigo con este tipo de comentario es peor que el
cdigo sin comentarios. Por otro lado, si los
comentarios son correctos pero slo repiten
verbosamente las sentencias de cdigo, no aaden
valor al cdigo mismo.

Los comentarios pobres o crpticos no son de mucha
ayuda y tienden a ser mal entendidos o pasados por
alto debido a que obstruyen la correcta
comprensin del cdigo.
24
El comentar efectivamente no consume mucho
tiempo. Los comentarios excesivos son tan malos
como la existencia de pocos de ellos, por lo que
lograr el equilibrio es importante.

Puede tomar mucho tiempo escribir comentarios por
dos razones comunes. La primera, el estilo de
comentarios puede consumir demasiado tiempo o
ser tedioso.

Un estilo que requiera mucho trabajo mantener es
un dolor de cabeza: Si los comentarios son difciles
de cambiar, no se cambiarn: se volvern imprecisos
y llevarn a confusin, lo cual es peor que no tener
comentarios del todo.
25
El comentar podra ser difcil debido a que las
palabras para describir lo que el programa est
haciendo no surgen fcilmente.

Eso usualmente es una seal de que no se entiende
bien lo que hace el programa.

El tiempo que se invierte en comentar es en
realidad tiempo invertido en comprender mejor el
programa, lo cual es tiempo que necesita invertirse
sin importar si lo comentas o no.
26
El ir comentando el cdigo a medida que se escribe
tiene la ventaja de que se va introduciendo
mientras ms frescos se tienen los detalles de
programacin. Comentar al final, por el contrario,
consume ms tiempo puesto que se deben recordar
los detalles y las sutiles suposiciones de la
programacin, o leer de nuevo el cdigo para
comprenderlo, antes de escribir los comentarios,
haciendo que estos sean menos precisos.

Si el cdigo requiere mucha concentracin es una
clara seal de que es complejo, pero una alternativa
sera utilizar el algoritmo como punto de partida
para la codificacin e ir convirtiendo las frases en
comentarios a medida que codificamos.
27
Si el diseo es difcil de codificar, hay que simplificarlo antes
de preocuparse del cdigo o los comentarios.

Si se usa un algoritmo (diagrama de flujo, pseudocdigo, etc.)
para clarificar ideas, la codificacin ser directa y los
comentarios automticos.

Los comentarios incrementan el tamao de los archivos de
cdigo fuente.

Aunque los compiladores modernos son capaces de obviar los
comentarios al momento de traducirlos a cdigo objeto y a
programas ejecutables, en algunos ambientes como la Internet
donde debe enviarse una copia del programa para ser
interpretado en mquinas clientes (cdigo ASP y applets de
Java y JavaScript, por ejemplo) el tiempo invertido en enviar la
informacin extra que representan los comentarios a travs de
la red puede ser prohibitivo pues penaliza el desempeo de las
aplicaciones, an si stas se ejecutan en hardware remoto
eficiente. Sin embargo, eso no quiere decir que no se deba
comentar el cdigo.
28
An as, una solucin prctica para este problema es
tener dos versiones del cdigo: una comentada y
otra en produccin. El truco consiste en escribir un
programa que filtre los comentarios de los archivos
fuente (que busque y deseche del cdigo todo el
texto que se halla protegido por las secuencias
sintcticas que el lenguaje usa para los comentarios)
antes de pasar al proceso de compilacin o
implantacin en los servidores de las aplicaciones
remotas.

El utilizar el algoritmo o el seudocdigo como punto
de partida para la codificacin tendr como efecto
colateral comentarios muy precisos.
29
Tcnicas para comentar cdigo
Comentarios por bloques: comentarios de una o dos
lneas que describan bloques de cdigo.

Escribe comentarios que describan la intencin del
cdigo: en lugar de repetir el cdigo, escribir
comentarios que describen el propsito del cdigo.

Enfoca tus esfuerzos de documentacin en el cdigo
mismo: el cdigo mismo debera ser la mejor
documentacin.

Enfoca el comentario del bloque en el por qu en lugar
del cmo: los comentarios que explican cmo se hace
algo estn a un nivel de programacin, algo tcnicos, en
lugar de estar a nivel del problema.
30
Evita las abreviaturas: los comentarios no deben
ser ambiguos, sino fcilmente legibles sin el trabajo
de adivinar abreviaturas.

Documenta las sorpresas: si hay lago que no es
obvio a partir del cdigo mismo. Cada truco tcnico
que se use debera ser comentado.

Comenta cualquier truco que evite un error o una
funcionalidad no documentada en un lenguaje o
entorno: si es un error, probablemente no est
documentado. An si est documentado en alguna
parte, no daa el documentarlo de nuevo en tu
cdigo. Si es una funcionalidad indocumentada,
debera estarlo en tu cdigo
31
Comenta las unidades de datos numricos: cada
variable o campo que vaya a contener cantidades
numricas que representen unidades de medida
debera tener documentada la unidad de medida
que representa. As, si una variable representar
longitud debera documentarse si representar
centmetros, pulgadas, metros, kilmetros, etc. Si
son coordenadas, si indicarn latitud, longitud o
altitud, y si est en grados o radianes; No asumas
que las unidades son obvias pues para un nuevo
programador u otro que est trabajando en otra
parte del programa/sistema, no lo sern.
32
Coloca un comentario antes de cada estructura de
control: las estructura de control a menudo
necesitan explicacin, y el mejor lugar para
documentarlas es justo el espacio antes de ellas. En
el caso de una sentencia de seleccin, debe incluirse
la razn para la decisin y un resumen del resultado.
Si es un ciclo, debe indicarse su propsito y aspectos
importantes de su ejecucin.

Describe cada funcin con una o dos oraciones en
la lnea anterior a ella: un comentario descriptivo
breve permitir conocer rpidamente el propsito
de la funcin. Si tienes dificultades en crear una
descripcin corta para la rutina es una clara seal de
que el diseo de tu programa no es tan bueno como
debera.
33
Documenta los parmetros de entrada y salida: la
forma ms prctica de documentar variables de entrada
y salida de una funcin es colocar esos comentarios
justo bajo la lnea de encabezado de la rutina misma.

Comenta las limitaciones de la funcin: si la funcin
devuelve un resultado numrico, indica su precisin. Si
la rutina funciona slo para estructuras de datos de
cierto tamao, indcalo. Si se sabe de modificaciones
que harn que la rutina deje de funcionar,
documentarlas tambin. Documenta los efectos globales
de las modificaciones que realiza la rutina

Si dentro de la rutina se modifica una variable o
estructura de datos global: debe describirse de forma
explcita esta modificacin.

34