Hoy vamos a hablar de documentación, tema demasiado importante y que siempre se deja de lado.
Siempre sucede lo mismo, como generalmente desarrollamos solos, no nos interesa que otros lean nuestro código, pero en el sector productivo es muy importante el trabajo en equipo y por lo tanto la documentación, tenemos que pensar que nuestro código sera una parte del producto final y que no va a ser una pieza asilada.
Para documentar un método se pueden tener en cuenta 6 partes.
- Nombre completo del método.
- Propósito del método.
- Descripción del método.
- Autor original.
- Modificaciones que se le han hecho.
- Autores que realizan las modificaciones.
Además es necesario mencionar si existe algún problema con el método, explicar brevemente las entras y salidas.
Otra recomendación es usar un lenguaje sencillo pero utilizando términos técnicos. También evitar comentarios obvios, comentar los sets y gets. Por ultimo es recomendable agrupar las notas, a no ser que sea una anotación muy importante para una linea.
Ah se me olvidaba un buen ejercicio es documentar en ingles por obvias razones.
No hay comentarios:
Publicar un comentario