Este puede ser un tema un poco polémico incluso conmigo mismo, pues de hace unos años para acá vengo siendo adicto a tomar notas y he notado que muchas veces escribo notas con la intención de reforzar el conocimiento y consultarlas en un futuro, sin embargo, son pocas las ocasiones en las que consulto.
Es un problema que me ha llevado a tener notas en varios archivos txt, notas en Google drive, notas en Trello, incluso notas dentro del mismo código y por supuesto este blog es también es un espacio que uso para escribir una suerte de notas definitivas, esto ha generado el problema que las notas se encuentren dispersas en varios lugares y pierda el tiempo buscando la nota que necesito realmente consultar.
Entonces he tomado una decisión y es la de tomar notas dentro del mismo código junto con algún trozo de código de ejemplo, de esta manera me evito escribir por separado en ubicaciones aleatorias notas que seguramente perderé, también evito perder el tiempo al tener que cambiar de ventana por consultar notas en otra parte, para luego regresar al código. Si por algún motivo necesito escribir algo que no tenga que ver con programación, lo escribiré en formato Mark Down o en HTML, así me obligo un poco más a codificar.
Me he dado cuenta que si hago pequeños trozos de código a modo de ejemplo básico para una característica que necesito y dentro del código comento cómo funciona cierta característica, usualmente consulto mucho más, esto me ha resultado realmente efectivo; eso lo he notado últimamente con un proyecto de interfaces gráficas con #tkinter.
¿Como aprovechar las notas para generar documentación?
Hace tiempo cuando programaba en Unity antes de quemarme, una vez noté que en C# existía una manera de documentar los comentarios, ya que los comentarios de C# son código XML, había una herramienta que convertía los mismos comentarios en documentación, para JavaScript existe algo llamado #JSDoc y en Python existe #PyDoc, que extrae del código los comentarios para documentarlos, aunque aún no he probado documentar comentarios con Python, haré una prueba en breve y lo traeré en un post.
Otra cosa que pienso que es necesario hacerlo, es subir la documentación en un repositorio de GitHub usando GIT, que es una herramienta que nunca uso, pero así me obligo a usarlo en serio, ya que la industria sobrevalora esta herramienta, sin embargo para mi es la cosa más inútil, no obstante de esta manera, tendré un control de los cambios que realizo en la documentación, refinándola con el tiempo, esto puede que sea positivo para cuando un reclutador revisa tu GitHub para que detecte actividad y vea el tiempo dedicado, aunque normalmente los reclutadores en Colombia se fijan muy poco en los proyectos que subas a GitHub solo a menos que sea que recibas muchas estrellas.
Soy consciente que este puede ser una forma más para agregar caos mis notas que ya son el caos, estaré haciendo pruebas y en unos meses comentaré que tal ha sido la experiencia.
Quisiera saber qué opinas o si conoces otra manera mejora de documentar código, notas y demás que sea útil y práctica, por favor comparte en los comentarios.
Nos vemos en un próximo post.
Comments