De la Documentación y Otros Demonios

Las dos cosas que no le gustan a los programadores son escribir pruebas(tests) y documentar. Buen, puede que a los más educados, juiciosos u organizados no les cueste e incluso les guste pero hay quienes sí nos cuesta un poco más.

El tema es que ambas son muy importantes. Los pruebas ayudan a garantizar que tu código en realidad hace lo que tiene que hacer y la documentación permite, en el mediano y largo plazo, que otros puedan leer, entender y usar tu código sin mayores complicaciones. Incluso podría servirte a ti mismo.

Pero, ¿y por qué cuesta tanto hacer ambas si son tan útiles? Creo que es cuestión de desconocimiento de las formas sencillas para lograrlo. Para el caso de los tests es importante escoger el framework o librería que nos permita acostumbrarnos a hacerlo con frecuencia y para documentar usar herramientas que la generen a partir del código fuente.

En este artículo no está contemplado escribir sobre testing así que se omite. Conozcamos un poco más sobre cómo documentar aplicaciones Ruby on Rails. Aunque vale la pena mencionar que algunas herramientas sirven independientemente del lenguaje y/o framework.

Conceptos

Antes de mencionar herramientas, recursos o cualquier otra cosa, considero útil sacar a relucir conceptos importantes o especie de guías para tener en cuenta durante este proceso. Una de ellas, y muy bien construida, es El Arte del README.

Seguramente, en proyectos de código libre has visto ese archivo llamado README.md. Tal archivo contiene la información básica para empezar a usar la herramienta, framework, gema, módulo, librería, etc. Es la primera cara de un visitante a tu código fuente en Github o Bitbucket.

Pues bien, resulta con unas personas se dieron a la labor de hacer una guía de qué información y cómo debería estar organizada dichos datos en un archivo README.md. Si en verdad estás pensando en documentar tu proyecto, un gran primer paso es dar una leída a Art of README(en inglés).

Por otro lado, en un artículo del blog de Aaron Summer, también se menciona la importancia de tener un buen README.md además de:

  • Excluir la documentación automática del Git o SVN
  • Documentar lo necesario y útil
  • Escribir documentación clara sin asumir lo que los demás saben o no de tu proyecto.
  • Entre otras cosas que se mencionan en el artículo.

Considero que es valioso definir unos preceptos por los cuales guiarse y los dos recursos anteriores proveen unas bases solidas para iniciar.

Ahora sí, el meollo del asunto.

comentarios como documentacion

Herramientas para Documentar APIs

Hay muchas pero destaco pocas: Apiary, Swagger y Slate.

Apiary es un servicio, más que una herramienta, pero es popular ya que trabaja con el formato API Blueprint para documentar APIs.

Ver una lista de ejemplos de documentación usando API Blueprint en Github.

Swagger es de los más reconocidos(en su página dice que es el más popular del mundo), sirve para una gran variedad de lenguajes y cuenta con un buen abanico de sub-herramientas para generar documentación para APIs.

Slate es otra herramienta y se caracteriza por permitir crear documentación que visualmente se parece a los docs de Stripe y PayPal. A diferencia de las dos anteriores, Slate emplea Markdown y HTML para editar los documentos y es fácil publicar en Github Pages o subiendo a un servidor web cualquiera.

Así luce una documentación creada con Slate. Cabe destacar que todo se puede modificar.

Generadores

También es posible usar generadores que se integran fácilmente en el código fuente mediante comentarios con una estructura definida y que interpreta dichos comentarios para luego producir archivos .html que se pueden montar en un sitio web.

Normalmente, la documentación se produce introduciendo algún comando en la consola, dejando los archivos en algún directorio que se especifique. Lo generado incluye, en la mayoría de los casos, hojas de estilos, javascripts y la información en documentos .html. Todos son modificables pero es del programador encontrar una forma en que cada vez que se genere, no se pierdan los cambios hechos.

Algunos de estos generadores son RDoc, YARD, SDoc y TomDoc.

En algunos proyectos se puede ver que se utiliza YARD como generador de documentación, el proyecto Ruby on Rails emplea a RDoc pero cuando ejecutas el comando rails new app el generador por defecto es SDoc. Un poco extraño eso.

Lo bueno de estos generadores es que no generan una dependencia total y puedes cambiar entre uno y otro sin mayores complicaciones.

Cuando se usa RSpec

RSpec es una gema usada generalmente cuando se desarrolla sobre Ruby on Rails para escribir tests.

Algunas de las formas de generar documentación desde los tests examples (así se les llama) es utilizando gemas que agregan algunas sentencias extra.

En un artículo en el blog de CodeShip sugieren utilizar dos gemas: Apipie-rails y rspec_api_documentation.

Por su parte, la gema RSpec API Blueprint formatter hace uso del formato que mencionaba anteriormente mediante instrucciones en las pruebas escritas en los archivos *_spec.rb.

it 'retrievs the patients medications' do
    retrieve_medications
    expect(JSON.parse(response.body).length).to eql 1
    expect(response).to have_http_status(:ok)
end

Hay distintas formas de documentar tu código y/o proyecto. Cual escojas no es lo más importante sino que lo hagas, poco a poco y constantemente.

Autor: cesc1989

Ingeniero de Sistemas que le gusta escribir y compartir sobre recursos que considera útiles, además que le gusta leer manga y ver anime.

Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión / Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión / Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión / Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión / Cambiar )

Conectando a %s