Documenting C Data Structures
Cuando se pida código C para esta materia, genera el archivo completo siguiendo este esqueleto:
C/* Name: nombre_del_archivo.c Copyright: Author: Alan Israel García Velasco Description: Explicación clara del propósito del programa, qué problema de organización de datos resuelve y cómo administra la memoria. */ // Directivas al preprocesador #include <stdio.h> #include <stdlib.h> #define VERDADERO 1 #define FALSO 0 /* Name: nombre_de_la_funcion Copyright: Author: Alan Israel García Velasco Description: Qué hace la función paso a paso y cómo altera el estado de la memoria. Parámetros: parametro_1: Qué dato es y qué función cumple. Regreso: TIPO: Qué valor devuelve y qué significa cada caso. */
Progress:
- Identificar la estructura de datos pedida (arreglo dinámico, pila, cola, lista, árbol, grafo, ordenamiento, hash) y su unidad temática
- Escribir encabezado de archivo (Plantilla 1) con nombre de archivo descriptivo en snake_case +
.c - Escribir sección
// Directivas al preprocesadorcon includes y#define VERDADERO 1/#define FALSO 0si hay lógica booleana - Declarar
struct/typedefnecesarios antes de las funciones - Por cada función: anteponer ficha de función (Plantilla 2) completa, con cada parámetro y cada caso de retorno documentado
- Dentro de cada función: comentar con
/* Explicación */antes de ciclos/decisiones, y con//al final de línea para movimientos de punteros/memoria - Añadir
// Función principalantes deint main() - Revisar que no haya fechas, versiones, timestamps ni estilos Doxygen/Javadoc (
@param,@return, etc.) - Verificar que el campo
Authorsea exactamenteAlan Israel García VelascoyCopyright:quede vacío
Example 1:
Input: "Hazme una pila (stack) dinámica con push y pop en C para la materia."
Output: Archivo pila_dinamica.c con encabezado de archivo, typedef struct del nodo, funciones push y pop cada una con su ficha completa (Parámetros/Regreso), comentarios /* Explicación */ antes de validar pila vacía/llena, comentarios // en cada reasignación de apuntador (nuevo->siguiente = *cima;), y // Función principal antes de un main() de prueba.
Example 2:
Input: "Corrige este código de un árbol binario que no libera bien la memoria."
Output: El código corregido conservando la lógica del alumno pero reescribiendo/añadiendo las fichas de función faltantes, agregando comentarios // en cada free() explicando qué nodo se libera y por qué, sin tocar el campo Author ni agregar fechas.
- Usa tabulaciones (no espacios) dentro de los bloques de comentario
/* ... */, replicando exactamente el formato de las plantillas. - Explica siempre el porqué del movimiento de memoria, no solo el qué: por qué doble apuntador, qué condición desborda la estructura, qué pasa si
mallocfalla. - Prefiere nombres de variables con prefijo de tipo cuando el material original lo usa (
iValor,iFrente,nNodo) para mantener consistencia con el banco de ejemplos. - En funciones recursivas, documenta explícitamente el caso base dentro del cuerpo con
/* Caso base: ... */. - Si la función puede fallar (malloc NULL, estructura vacía/llena), documenta cada valor de retorno posible en la sección
Regreso:como una lista de casos. - Lenguaje de comentarios: directo, sin tecnicismo inflado, como si se explicara a un compañero de clase.
- No uses
@param,@brief,@returnni ningún tag de Doxygen/Javadoc — rompe el estándar. - No agregues fecha, hora, número de versión ni "Last modified" en ningún encabezado.
- No dejes el campo
Copyright:con texto; debe quedar vacío tras los dos puntos. - No cambies el autor ni lo pluralices/abreves; siempre
Alan Israel García Velascotal cual. - No omitas la ficha de función en funciones auxiliares pequeñas (como
buscar_minimoocola_vacia); todas llevan su ficha completa. - No mezcles espacios y tabs de forma inconsistente entre comentarios del mismo archivo.