Buenas Practicas De Programacion READMEs
Un README es un archivo que entre otras cosas indica para que es el programa, como se instala, como se usa y algunos ejemplos.
Un poco de historia de los READMEs
En la época que todo el software era empresarial o creado por las universidades la documentación era amplia y muy formal siguiendo estándares como el MIL STD 498, que siguen siendo muy útiles, pero para muchos proyectos pequeños son demasiado vastos. Por otro lado, los hackers que utilizaban unix creaban su documentación como páginas man, por el comando que permitía visualizar como se utilizaba un comando los primeros ejemplos de README son de ésta época y su uso en la industria del software es tan extendido que son parte del GNU Coding Standard.
En la época del warez, cuando la gente comenzaba a utilizar computadoras personales, muchos programas crackeados, y software pequeño para ser utilizado en máquinas Windows comenzó a incluir pequeños archivos de texto donde se explicaba la operación del software, como instalarlo y que equipo era responsable por el crack. Estos archivos se conocen por el nombre genérico de README (Leeme, en inglés).
La época de Github
Recientemente Github a popularizado el uso de READMEs en proyectos de software si se incluye un README en la raíz de un proyecto este es automáticamente presentado en la página principal. en general es un documento de texto pero Github prefiere utilizar el formato Maarkdown.
Que contiene un buen README
Un buen README en formato Markdown cuenta con las siguientes características:
- El título, preferentemente el nombre del proyecto
- Una introducción al proyecto
- Una tabla de contenidos
- Subtítulos o títulos internos (para las secciones)
- Un logo, ícono o captura de pantalla
- Los nombres de los desarrolladores y su correo
- Las tecnologías utilizadas y las dependencias del proyecto
- El método de instalación
- Ejemplos de uso
- Fuentes o algoritmos utilizados
- El status del proyecto o un link a las pruebas
Estos elementos le dan claridad al proyecto y no son demasiados como para que no los utilicemos incluso aunque sea un proyecto pequeño, esto aparte de permitir a otras personas utilizar nuestro código, si lo ponemos en un repositorio público muestra a otros programadores y a los reclutadores la calidad de nuestro trabajo.
Conclusiones
Escribir un buen README es parte importante de la documentación y distribución de un proyecto, especialmente si es software libre de código abierto pero, incluso si es un proyecto cerrado, los READMEs son una gran ayuda para incorporar programadores rápidamente a un proyecto.