2013-09-15

Como documentar tu codigo fuente



Sin duda es uno de los puntos que no nos agrada LA DOCUMENTACION, mas sin embargo es importante tanto para tu equipo de trabajo y para nosotros mismo, esto debido a que no siempre recordamos todo y cuando alguien viene a dar mantenimiento a nuestros garabatos se le dificultara y a su vez se convierte en pérdida de tiempo, así que dejo un resumen de que podemos hacer para tomar en cuenta en nuestros proyectos y algunos enlaces de apoyo:

  • Comenta solo el codigo que no pueda decir la funcionalidad por si mismo
  • Comenta a varios niveles (recuerda hacerlo uniformemente)
    • Documentacion por clases (descripcion,autor,fecha y ultima modificacion)
    • Documentacion por metodo (descricpion del objeto, funcionalidades, parametros y resultados)
    • Documentacion de variables IMPORTANTES
    • Documentacion de limitaciones
    • Documentacion de algoritmos implementados
Recuerda hacer los estandares que se llevaran acabo con tu equipo de trabajo es importante definir las sintaxis para llevar un mismo lineamiento, ademas existe en VS tags que puedne apoyarte en facilitar estas tareas.
  • Usa parrafos comentados (no uses solo una linea dividela en parrafos para que sea mas legible)

// Comprobamos si todos los datos
// son correctos
foreach (Record record in records){
    if (rec.checkStatus()==Status.OK){
        ...
    }
}
  • Tabular los comentarios de lineas consecutivas

const MAX_ITEMS = 10; // Número máximo de paquetes
const MASK = 0x1F;    // Máscara de bits TCP
  • No dudes de la capacidad de analisis de tu equipo

if (a == 5)     // Si a vale cinco, ...
    counter = 0; // ... ponemos el contador a cero
    ...
  • Se profesional (No insultes o coloques frases fuera de contexto de lo que es tu trabajo)
    • Ejemplo: "este parche corrije el efecto colateral producido por la patética implementación del inepto desarrollador inicial"
  • Revisa la ortografia
  • No comentes si no es necesario y en caso de ser necesario solo se simple y directo
  • Piensa a futuro y escribe la idea que te gustaria leer si fuera el caso en que tu revisaras la documentacion para alguna correcion
  • TODO es esencial en trabajos de equipo
  • Documenta mientras desarrollas NO DESPUES ya que pudieras NO recordar detalles esenciales despues
  • Actualiza los comentarios asi como el codigo fuente
  • Regla de oro ESCRIBE CODIGO LEGIBLE a la vista (a menos que sea JAVASCRIPT :)
  • Evangeliza a los de tu equipo con estas buenas practicas, por el bien comun.