RE:Guía para hacer comentarios o documentar el cód
Hola, Orlando:
En mi empresa existe una especie de plantilla que todos los programadores debemos seguir. A grandes rasgo, es como sigue:
Al inicio de cada formulario o módulo de código debe existir un ´bloque documentado con la siguiente información:
1. nombre del módulo o formulario.
2. nombre de la aplicación para la que se realiza indicando, si es necesario, de qué otra aplicación se ha cogido o modificado.
3. autor (nombre y apellidos) y fecha del formulario (dd-mm-aaaa)
4. autor y fecha de las siguientes modificaciones
5. objeto del formulario o módulo
6. referencias o componentes utilzados (historial)
7. comentarios.
Para cada función o procedimiento del formulario, otro bloque al inicio con el siguiente formato:
1. nombre de la función o procedimiento.
2. objetivo del mismo
3. descripción del mismo
4. precondiciones para la llamada
5. postcondiciones para la llamada
6. parámetros y descripción de los mismos
Para los tipos de datos, constantes, estructuras, variables y demás, una explicación lo más detallada posible de su necesidad.
Además, todas las variables, constantes, componentes, controles y demás llevan una nomenclatura específica, de forma que se sepa qué es simplemente viendo el nombre de la variable o lo que sea.
- Prohibido usar GOTO salvo en control de errores (on error goto...)
- Prohibido duplicar código si puede evitarse (y casi siempre puede evitarse)
- Prohibido usar recursividad, salvo casos muy muy específicos y muy muy documentados y siempre bajo la aprobación del jefe de proyecto (que casi nunca los apruebo).
- Identación de tres espacios en blanco
- Comentar las líneas de código y no dar nada por supuesto...
El objetivo de esto es que cualquier desarrollador que venga pueda seguir el trabajo sin problemas.
En http://www.eidos.es/VexPERT/
puedes encontrar un artículo muy bueno al respecto.
Un saludo.
