Archivo de la etiqueta: programación

Mis reglas para un mejor software científico

Hace tiempo que no escribo sobre mis reglas ser más eficiente y qué mejor excusa que este artículo sobre reglas para un software científico más robusto que me ha pasado mi hermano para aprovechar y contar un poco cómo me apaño yo, simple investigadora sin conocimientos de informática, para gestionar todo el código que tengo que escribir y usar.

No, no sé programar

Os va a parecer muy loco pero yo, al igual que muchos otros científicos e investigadores, programo en mi día a día sin tener ningún tipo de formación en ello. No tengo ningún conocimiento sobre cómo programar, sobre tests o sobre buscar bugs. Cero patatero. Y eso que yo soy muy poco convencional y uso la terminal y tengo mi código bajo control del versiones.

De hecho, este es mi sexto año currando en una universidad, es la cuarta en la que estoy (contando también en la que estudié) y no es nada común, al menos en mi campo (¡la ingeniería mecánica!), que la gente sepa usar el ordenador y ya ni hablemos de programar con cierto sentido. ¡Pero mucha de esta gente programa, yo incluida! ¿Cómo lo hacéis? os preguntaréis. Pues fácil: a lo salvaje, con un código repetitivo, lleno de basuras e imposible de leer para cualquiera que no sea su creador en los siguientes 15 minutos de haberlo escrito.

Lo peor de esto es que ese código ineficiente y chapucero viaja por ahí en emails y pendrives y miles de millones de versiones diferentes de él circulan por ahí a cada cual más desastrosa… No exagero nada cuando digo que he llegado a escribir programas (programas complejos) desde cero porque no era capaz de entender lo que me habían pasado, es decir, una carpeta llena de funciones sin la más mínima documentación.

Como comprenderéis, esto es frustrante y una pérdida de tiempo tanto para el que escribe como para el que usa el programa y además retrasa el avance de la ciencia, ya que no permite que se creen soluciones serias para atacar los problemas sino que cada cual se hace su herramienta cutre para salvar su culo.

En fin, después de este desahogo me centro ya en lo que estábamos: unos criterios para que el código que escribimos los que no sabemos programar sea un poco más usable. Estas son las reglas que yo misma intento seguir para mi código, las considero una buenas prácticas que harán la vida de Ondiz del futuro más simple ya que no tendrá que retrotraerse a aquella vez que le pasaron 5 gigas de datos que tenía que tratar en una semana porque tenía una reunión. Estas reglas son, además, perfectamente adaptables a la producción de textos científicos y veréis como tienen mucho en común con mi proceso de escritura LaTeXiano.

Lo último que tenéis que saber antes de leerlas es que he adaptado la información que he leído con mi experiencia personal y por eso están escritas en plan bronca hacia mí misma. ¡Vayamos a ellas!

Cinco reglas simples y un bonus

Primera regla: usa control de versiones

¡Nunca me cansaré de repetir esto! Ponte ya mismo a aprender a utilizar un sistema de control de versiones, me da igual cuál. Yo uso git cuyas funcionalidades básicas se aprenden en un rato y que tiene múltiples GUIs disponibles si te da miedito la terminal, pero puedes elegir el sistema que te parezca siempre que empieces a usar uno ahora.


No me pruebes por amor de Dios una nueva funcionalidad y destruyas todo lo hecho hasta ahora porque tu único salvavidas es el botón de deshacer y el archivo aquel que se llama versión_corregida_final_57.

Corolario: usa texto plano

Para que el sistema de control de versiones sea útil de verdad lo mejor es que te pases al texto plano. Podrás ver las modificaciones introducidas con una facilidad pasmosa (¡diff!), no te tirarás de los pelos cuando la versión del software cambie y serás más feliz en tu vida en general.

Segundo corolario: usa un editor decente

Con editor decente me refiero a uno que te ayude en tu trabajo, no uno que luche en tu contra (¡hola, Word!). Un editor que maneje texto plano y facilite tareas como buscar o escribir una tabla te hará ahorrar horas de trabajo. Si este editor es configurable y puedes adaptarlo a tu gusto ya ni te cuento.

¿He oído Emacs por ahí? ¿Vim dicen aquellos otros? Me vale cualquiera que no se cuelgue al abrir un csv de 100MB.

Segunda regla: documenta el código

Ahora te parece que esa función que ensambla matrices dispersas y que has escrito en una línea con variables que se llaman a, b y c se explica por sí misma, pero cuando vuelvas el lunes te darás cuenta de que no es así1. Cuando te aparezcan errores crípticos y hayas tenido que reescribir lo que hiciste ayer porque no te acuerdas de cómo lo implementaste te lamentarás de no haber documentado tu proceso.

Tampoco te pido que pongas todos los detalles, con una línea diciendo qué hace la función, cuáles son sus entradas y salidas y un ejemplo de uso es más que suficiente. Si quieres tener algo más decente, puedes investigar el sistema de documentación específico de tu lenguaje, por ejemplo, en Matlab se pueden hacer cosas chulas en HTML.

Corolario: escribe para las personas no para el ordenador

No me sirve de nada que generes código como churros si luego nadie (¡ni siquiera tú mismo!) es capaz de usarlo. Ten en mente a la persona a la que le tocará añadir un nuevo módulo a tu programa cuando escribas y explica por qué has tomado una decisión y no otra.

Tercera regla: añade un README

Una situación bastante típica si eres investigadora es que te pasen una carpeta llena de scripts sin ton ni son y te digan que ese es el trabajo hecho hasta el momento y que le añadas la opción X. Con el simple hecho de que en esa carpeta haya un README en el que se resuma el objetivo final de todos esos archivos sueltos y qué hace cada uno, la persona que la reciba pasará de estar un par de semanas tirándose de los pelos a solo un par de horas.


Si en ese README hay además una descripción de las herramientas necesarias (con sus correspondientes versiones) para poder usar ese código y una microexplicación de cómo se usa, la persona que reciba tu trabajo te amará por siempre jamás. Si está escrito en Markdown o en Org para que mi editor decente me lo muestre con colorinchis para que sea más fácil de leer yo también te amaré.

Cuarta regla: proporciona un ejemplo de uso

Siguiendo con la regla anterior, lo mejor que puedes hacer por las que usarán tu trabajo en el futuro (y recuerda que puedes ser tú mismo) es proporcionar un ejemplo. Puede estar en el propio README o que haya un caso mínimo incluido en la carpeta con las cosas donde se muestre el funcionamiento de tu programa, como tú veas, pero por dios, hazlo. Es la mejor manera de que yo sepa que tu programa funciona.

Quinta regla: no des por hecho nada

No asumas que los archivos estarán en un lugar concreto y no me escribas rutas absolutas que solo funcionan en tu ordenador. Si tu programa usa herramientas externas, búscalas o dime dónde situarlas en el README, pero que no tenga que estar como Colombo intentando localizar el origen de un error.

Regla del opensource: si publicas tu código hazlo en condiciones

Esta última regla la digo más que nada como usuaria de programas y paquetes de diferentes repositorios. Por favor, etiqueta las versiones, avisa de las dependencias, usa un proceso de instalación típico, añade una licencia y especifica qué falta por hacer. A ti te lleva muy poco tiempo hacer estas cosas pero a mí me libras de muchas horas de frustración. Hazlo por mí.

Recapitulación

Vas a tener que programar aunque no sepas así que ten en mente dos cosas: usa las herramientas adecuadas y pónselo fácil a las personas. Piensa que solo con cambiar a un editor más potente aumentarás tu productividad de manera loca y que un simple README de tres líneas hará tu programa mucho más usable para todo el mundo, ¡especialmente a tu futuro tú!

Referencias

Ten simple rules for making research software more robust

Ten recommendations for creating usable bioinformatics command line software

Best practices for scientific computing (pdf)

Your step-by-step guide to more effective documentation


¡Música!


  1. Esto es un caso real de cuando calculaba los modos de una viga con elementos finitos en Matlab. 
Anuncios

Lo que he aprendido: compilar Emacs desde fuente

¡Saludos damas y caballeros! Vuelvo después de mis merecidas vacaciones con el frikismo recargado. Digo esto porque estuve de visita en casa de un amigo que compiló Emacs 25 desde fuente delante de mí y ha provocado que tenga envidia y quiera compilar yo también. Y eso os vengo a contar, mi experiencia creando Emacs desde sus piezas más elementales desde mi punto de vista de ignorante de la informática.

¿Compilar?

No es mi primera vez compilando, es concretamente la segunda. La primera fue con pdfpc que compilé tanto en Windows como en GNU/Linux invocando a cmake para que crease las instrucciones, luego a make para que compilase y finalmente a make install para que me instalase el programa en las carpetas correctas.

Compilar Emacs es similar solo que en lugar de llamar a cmake usamos el script configure, un script estándar para los programas de GNU que verifica que el sistema cumple las condiciones para compilar el programa en cuestión y crea las instrucciones para make.

Que los programas de GNU se compilen siempre de la misma manera es debido al conjunto de herramientas GNU Build System o Autotools, que ayudan a crear paquetes de código portables para que los programadores se centren en la funcionalidad de sus programas y que los usuarios solo tengan que aprender el método para compilar una única vez.

He resumido lo que he entendido de este proceso en un dibujillo, para que luego sepamos más o menos dónde estamos:

¡A compilar Emacs!

Después de esta pequeña introducción vamos a ensuciarnos las manoplas. Los pasos que seguiremos son:

  1. Descargaremos el código fuente
  2. Si hemos clonado de un repo ejecutaremos autogen.sh para obtener el script configure
  3. Ejecutaremos configure con las opciones que queramos
  4. Llamaremos a make que nos fabricará Emacs
  5. Si queremos instalar Emacs en las carpetas de instalación haremos make install

Veamos cuál ha sido mi experiencia con sus problemas y soluciones.

Descargar el código fuente

Evidentemente, lo primero que necesitamos para compilar desde fuente es el código fuente. Para conseguirlo tenemos dos opciones:

  • Descargar la release desde la web a mano, con wget o como nos parezca. En este caso empezamos directamente con el script configure, siguiendo las instrucciones del archivo INSTALL.
  • Clonar desde el repositorio de GitHub o Savannah. Obedeceremos a INSTALL.REPO que nos manda ejecutar autogen.sh para que aparezca el famoso configure.

El script autogen.sh

Como yo siempre sigo el camino más difícil, cloné el repo de GitHub y por lo tanto tuve que invocar primero a autogen.sh. Para ello necesité primero instalar Autoconf, una de las herramientas que conforman el GNU Build System y que se encarga de crear el script configure a partir del archivo configure.ac. Como suele ser habitual, hice:

sudo apt-get install autoconf

En el caso de que descarguemos la release no tenemos que fabricar el script configure sino que ya viene incluido.

El script configure

Ahora nos toca ejecutar configure para que nos verifique si tenemos todas las librerías necesarias instaladas y genere finalmente el Makefile si es así. También podemos pasarle diferentes opciones para controlar el proceso, con --help vemos cuáles hay.

Por ejemplo, yo utilicé --prefix para elegir el destino en el que quería que se instalase Emacs. No quería que lo instalase en el directorio por defecto /usr/local/ porque solo estaba haciendo unas pruebas:

ondiz@slimbook:~/Testing/emacs$ ./configure --prefix=/home/ondiz/Testing/

Nos irá diciendo qué dependencias tenemos que resolver y la opciones que debemos darle si no queremos usarlas con un mensaje de este estilo:

configure: error: The following required libraries were not found:
libXpm libjpeg libgif/libungif libtiff gnutls
Maybe some development libraries/packages are missing?
If you don't want to link with them give
--with-xpm=no --with-jpeg=no --with-gif=no --with-tiff=no --with-gnutls=no
as options to configure

Sigue leyendo

Lo que he aprendido: registro de cambios en un documento LaTeX con git

Estoy echando una mano a mi hermano con una documentación to guapa para un tema que mejor os cuenta él y me preguntó cómo incluir un registro de cambios en el documento. Un registro de cambios no puede ser muy complejo de hacer si estamos usando git, pensé, así que me puse a investigar las diferentes alternativas, empezando por la opción evidente: git log.

Jugando con git log

Empecemos por los inicios, como todos los que usáis git sabéis mejor que yo, git log nos permite dar un formato al historial de commits con las opciones --pretty y --format. Por ejemplo, podemos mostrar la fecha y la descripción del commit haciendo:

git log --pretty=format:"%ad%x09%s" --date=short > cambios.log

Seguir leyendo →

Lo que he aprendido: programar tareas desde cmd en Windows

Siguiendo en mi cruzada de hacer que el ordenador trabaje mientras yo leo movidas en el interneto, he aprendido a “retrasar” una tarea en Windows sin usar el Programador de tareas: usar el comando timeout. Lo que hace es esperar un determinado tiempo antes de ejecutar el próximo comando. Es megaguay porque pone una cuenta atrás y parece que el ordenador va a explotar o algo. Es especialmente interesante para usarlo en un ordenador comunitario y no avisar a los demás de lo que andas tramando. Sí, soy malvada y me encanta.

Es tan fácil de usar como hacer:

timeout <T>

Donde <T> es el tiempo que tiene que esperar en segundos. Tenemos la opción de añadir /nobreak para que si alguien pulsa una tecla no se nos active la tarea.

De propinilla vamos a aprender cómo escribir comentarios en la línea de comandos de Windows:

  • Comentar línea completa: usamos ::
  • Comentario dentro de la línea: usamos & :: ya que el & es el comando separador de líneas, es decir, permite poner varios comandos en una única línea.

Lo he usado para programar un cálculo de Abaqus y aprovechar el ordenador por la noche. Para ello he creado un archivo cmd y he escrito lo siguiente en él:

:: Wait 10'
timeout 600 /nobreak 
abaqus job=<JOBNAME> interactive
pause & :: wait until keystroke

El pause del final es para que no se me cierre la ventanita al acabar y poder ver cómo ha ido el tema la mañana siguiente.

Nada más por hoy, estamos un poco más cerca de este señor 😛

Fuentes

Man de timeout

How to comment in Windows command line? en StackOverflow

10 Keys to Command Shell Scripting

Difference Between CMD and BAT

Lo que he aprendido: código en un documento con pandoc

Siguiendo con nuestro plan de dominación mundial hoy vamos a poner código con sintaxis resaltada con su pie de código y su referencia usando Markdown, pandoc y pandoc-crossref. Veamos cómo.

Resulta que cuando metemos código entre las míticas ``` podemos poner como opciones el lenguaje y un pie de código:

```{.python caption="Code block"}
print 'Hello!'
```

Si además usamos el filtro pandoc-crossref podemos ponerle una etiqueta para referenciarlo en el texto, estas etiquetas tienen la estructura #lst:nombre_etiqueta:

```{#lst:codeBlock .python caption="Code block"}
print 'Hello!'
```

Seguir leyendo →

Lo que he aprendido: trucar paquetes de Latex

Os contaba hace tiempo cómo hacer una lista de símbolos en Latex sin enloquecer. Hoy os traigo la versión mejorada de esa lista porque como estoy ida de la cabeza he modificado el paquete para que cumpla con mis manías. Antes de nada he de decir que yo no tengo ni idea de programar cosas en Latex y es la primera vez que toco un paquete pero os quiero demostrar que estas cosas no son tan difíciles como parecen 😀

En nuestro caso vamos a modificar el paquete listofsymbols para que separe los símbolos de las letras griegas y los acrónimos. Para ello cogeremos el archivo sty, lo leeremos a ver si comprendemos lo que hace y lo trucaremos a nuestro gusto.

Echando un vistazo al código podemos ver que los símbolos se definen y se escriben en un archivo auxiliar sym:

\newcommand{\opensymdef}{\newwrite\@sym \immediate\openout\@sym=\jobname.sym}

\newcommand{\closesymdef}{\immediate\closeout\@sym}

Seguir leyendo →

Lo que he aprendido: programar el ordenador para que se apague solo

El otro día me pasó una cosa curiosa, le dije así sin darme cuenta a mi jefe que había programado el ordenador para que se apagara solo porque estaba calculando una historia y quería que terminase. La cuestión es que el pavo tiene envidia ahora y quiere que su ordenador también se apague solo. Luego se meten conmigo por friki pero no se dan cuenta de que la frikez es megaútil.

Os voy a contar a vosotros también cómo va la movida porsiaca. Recordemos que esto ocurrió en mi currelo así que estamos en Windows (así es la vida hermanos, te obligan a usar Windows en los trabajos). Lo que tenemos que hacer es una chorrada supina para nosotros los usuarios del terminal.

Vamos al cmd y escribimos:

shutdown /s /t TIEMPO_HASTA_APAGADO_EN_SEGUNDOS

Por ejemplo para apagarlo dentro de un minuto:

shutdown /s /t 60

Eso es la parte number one pero nosotros como vagancias que somos no queremos escribir eso una y otra vez. ¿La solución? El infrautilizado e infravalorado Programador de tareas. Vamos a él (Panel de control, Herramientas administrativas) y creamos una tarea nueva. En la pestaña de Desencadenadores le damos la fecha y hora en la que queremos que se apague el ordenata y en Acciones ponemos:

unnamed

Guardamos la tarea y tal lógicamente y la próxima vez que queramos usarla con editarla cambiando la hora ya lo tenemos.

Pues nada más señoras y señores, ¡enseñadles esto a vuestros jefes y hagamos que la frikez domine el mundo!