<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Nicolás Sanguinetti on Medium]]></title>
        <description><![CDATA[Stories by Nicolás Sanguinetti on Medium]]></description>
        <link>https://medium.com/@godfoca?source=rss-ec938de0c14------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/0*wqIHEhP7PFH2IAdu.jpg</url>
            <title>Stories by Nicolás Sanguinetti on Medium</title>
            <link>https://medium.com/@godfoca?source=rss-ec938de0c14------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sun, 22 Nov 2026 15:54:27 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@godfoca/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Ruby, types, and interfaces]]></title>
            <link>https://medium.com/@godfoca/ruby-types-and-interfaces-d8ae9003e127?source=rss-ec938de0c14------2</link>
            <guid isPermaLink="false">https://medium.com/p/d8ae9003e127</guid>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[ruby]]></category>
            <dc:creator><![CDATA[Nicolás Sanguinetti]]></dc:creator>
            <pubDate>Fri, 18 Nov 2016 12:27:06 GMT</pubDate>
            <atom:updated>2016-11-18T12:29:31.719Z</atom:updated>
            <cc:license>http://creativecommons.org/publicdomain/zero/1.0/</cc:license>
            <content:encoded><![CDATA[<p>The other day I was trying to understand why a test was failing. Spelunking through the code I ended up looking at one of the gems the app uses. In its code, I ran into something similar to this:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/d66031ae1d93a78ce598fe8378cf4e16/href">https://medium.com/media/d66031ae1d93a78ce598fe8378cf4e16/href</a></iframe><p>The idea being that the gem would call this method to test a URL path against a user-provided object, which—as you can see from the code—can be of many different types.</p><p>Looking at that, it got me thinking: Did the author(s) of this code really care about whether the filter was a Proc, or just any callable would&#39;ve worked? Did they <em>really</em> care whether it was a RegExp?</p><p>If someone implements an Array look-alike without inheriting (because, you know, <a href="http://words.steveklabnik.com/beware-subclassing-ruby-core-classes">inheriting from ruby’s core classes</a> is fraught with peril), do we care? Or do we just care that we get an object that responds to join?</p><p>For a language with such a strong advocacy of “<a href="https://en.wikipedia.org/wiki/Duck_typing">duck typing</a>”, there’s a lot of production code that just depends on the specific class of an object instead of caring about the messages it understands.</p><h4>Can we improve this?</h4><p>What would be the best way to check the messages each filter can respond to, instead of their explicit type?</p><p>An obvious first approach would be using if statements:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/197246f5e6a344a37ff2adeebf92ef35/href">https://medium.com/media/197246f5e6a344a37ff2adeebf92ef35/href</a></iframe><p>This is, however, a lot harder to read. Seeing a case in ruby immediately communicates that there&#39;s some pattern matching coming, instead of just &quot;a big conditional.&quot;</p><p>So, here’s a (tiny) experiment to preserve the pattern matching feeling:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/fb775aa74205d1a785d7998839042e47/href">https://medium.com/media/fb775aa74205d1a785d7998839042e47/href</a></iframe><p>Now we’re not restricting ourselves to the types we pass, but the interfaces they implement. Anything that implements call, or match, for example, will work. 👌</p><h4>Success?</h4><p>Not everything that shines is gold, however. And not everything that implements a method named join will behave similarly.</p><p>Enter Pathname. If this method could potentially receive a Pathname instead of an Array of strings, you&#39;d have a fun bug to catch:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/1aa2d677e752c18967a5e32e8cf34e94/href">https://medium.com/media/1aa2d677e752c18967a5e32e8cf34e94/href</a></iframe><p>You could work around this by saying Implements[:join, :each], to make sure we only target “joinable enumerables”.</p><p>However, that stops being transparent. It’s no longer obvious why we’re asking for things that implement join and each but then just call join on them. At this point we have to ask the same question we started with: In this case, do we care about the type of the thing, or the interface of the thing?</p><p>And in this particular case, the answer is probably that we care about the type (“a list of strings that give segments of a path”) rather than the interface.</p><h4>So should we use this, or not?</h4><p>The answer, <em>surprisingly</em>, is “maybe.” 😛</p><p>I’m not going to run and send pull requests for every type-matching case statement in the wild. And neither should you.</p><p>As always, you should be careful and think of the consequences of every single line of code you add (or remove).</p><p>Particularly, you should think about what each line of code communicates to its readers—whether that’s future you, your team, or a user of your library that’s beffuddled by a failing test.</p><p>(Which, by the way, had nothing to do with this code. Ended up being a stupid mistake I was doing elsewhere… as usual.)</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d8ae9003e127" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Sé Responsable]]></title>
            <link>https://medium.com/@godfoca/se-responsable-fd0237bf1a21?source=rss-ec938de0c14------2</link>
            <guid isPermaLink="false">https://medium.com/p/fd0237bf1a21</guid>
            <dc:creator><![CDATA[Nicolás Sanguinetti]]></dc:creator>
            <pubDate>Thu, 22 May 2014 03:18:08 GMT</pubDate>
            <atom:updated>2014-05-22T04:53:28.575Z</atom:updated>
            <content:encoded><![CDATA[<h4>Mi charla de RubyConf Uruguay 2014, en palabras</h4><p>Puedes encontrar los slides de esta charla en <a href="https://speakerdeck.com/foca/se-responsable">mi página de SpeakerDeck</a>.</p><p>Aparentemente voy a hablarles sobre responsabilidad. Los que me conocen saben que soy un irresponsable de mierda, así que no estoy muy seguro de cuánta autoridad tengo para hablar del tema.</p><p>Vamos a hablar de la responsabilidad que tenemos cada uno de nosotros al hacer nuestro trabajo como hacedores de software. La responsabilidad hacia nuestros usuarios, hacia nuestros pares, y hacia nosotros mismos.</p><h3>Responsabilidad con nuestros usuarios</h3><p>Esta es “fácil”. Don’t be Evil™. Es el slogan no-oficial de Google. Según ellos:</p><blockquote>Don’t be evil. We believe strongly that in the long term, we will be better served-as shareholders and in all other ways-by a company that does good things for the world even if we forgo some short term gains.</blockquote><blockquote>— Larry Page, <a href="http://investor.google.com/corporate/2004/ipo-founders-letter.html">Google’s IPO Founders Letter</a>.</blockquote><p>“No sean malos. Creemos firmemente que a largo plazo, nos va a hacer mejor—tanto como accionistas como en cualquier otra forma—ser parte de una empresa que hace cosas buenas por el mundo, incluso si eso quiere decir dejar de lado algunos objetivos a corto plazo.”</p><p>En el caso puntual de Google el contexto es “No nos vendemos. Los resultados de búsqueda van a ser lo mejor que los podamos ofrecer, y no ofrecemos a la venta un mejor posicionamiento, ni vamos a engañar a usuarios poniendo ads en lugares donde no estén claramente identificados como tales”.</p><p>Igual a donde yo quiero ir va un poco más allá de eso. Quiero que como programadores trabajemos siempre en algo que, de alguna forma, mejore un poco el mundo. Eso no quiere decir que tienen que salir a curar el cáncer y el hambre en África—aunque si lo hacen sería genial—pero tienen que ser buena gente en cómo encaran su trabajo. Lo que hagan, tiene que ser para mejorarle la vida a los que usen sus productos, no para cagársela.</p><p>Por ejemplo, hace mucho tiempo, un foca más joven (y con bastante más pelo) trabajaba en una empresa que vendía cosas mediante SMS. Ya la premisa era medio shady. El último producto en el que trabajé ahí era un sistema que le mandabas un SMS con una canción, la buscaba (la parte técnica de hacer procesamiento de lenguaje natural para encontrar cuál era la canción dado un término de búsqueda estaba re copada), y te ofrecía un pack de 3 canciones. Si aceptabas, te mandaba la canción que habías buscado y te dejaba dos creditos a tu favor.</p><p>Cuál era la idea? No-se-qué porcentaje altísimo de los usuarios después de comprar el primer ringtone no volvían a cobrar sus dos créditos restantes, y era plata con la que se quedaba la empresa.</p><p>Cuando traté de argumentar que eso era una mierda, El Jefe me mandó a pasear, porque la “gracia” era justamente explotar la distracción de la gente. Ese día empecé a buscar otro trabajo.</p><p>¿A qué voy con esto? Como programadores tenemos una responsabilidad ética con la gente. No podemos estar haciendo algo que joda a la gente para beneficiar a un pelotudo con plata.</p><p>De nuevo, no es un “salgan a curar el SIDA ya, OR ELSE”. No, tampoco quiero que seamos todos unos hippies de mierda cantando Kumbaya alrededor de una fogata. (Ojo, de nuevo, si pueden hacer algo que haga que menos gente se enferme de SIDA, awesome!). Lo que quiero es que cuando vayan a hacer algo, lo hagan pensando en “¿Cómo mejora esto la vida de quien lo va a usar?”</p><p>Quizás es algo que le hace ahorrar 30 minutos por día de trabajo porque hace un proceso más eficiente. Eso son 30 minutos que capaz que no tiene que quedarse tarde y puede pasarlo con la gente que le importa.</p><p>Quizás es un juego que mantiene a la persona entretenida y contenta.</p><p>Quizás es una tostadora transparente que hace que veas cuándo está pronta la tostada y te enojás menos con la vida porque se te queman menos las tostadas.</p><p>No importa qué es. Lo importante es que, como programadores, tenemos que comprometernos con que lo que sea que hagamos, sea para mejorar la vida de quienes lo usan. No tiene por qué ser una mejora sustancial. Pero no puede ser para empeorar la vida de nadie.</p><p>Bajemos un poco de lo abstracto. Más allá de las intenciones de fondo que uno tenga con el software que escribe, y de la discusión ética, hay algunas cosas que podemos hacer para que el software que hacemos sea el mejor que podemos hacer.</p><h4>Fácil y Simple</h4><p>Es importante que el servicio que brindemos sea comprensible. Cualquier herramienta que no lo sea, estamos condenando a nuestros usuarios a pasar mal tratando de usarla.</p><p>¿Cómo definimos “simple”? El origen de la palabra viene del latín, “sem-plex”, que quiere decir “un pliegue” / “una hebra”.</p><p>Esto es, “una parte”. Algo simple es algo que no tiene muchas partes. Algo que podemos comprender rápidamente porque no cuesta visualizarlo en su totalidad.</p><p>Esto es distinto de algo “fácil”. Algo fácil es algo que nos resulta familiar, algo que podemos comprender porque estamos acostumbrados a ello.</p><p>Simple es una medida absoluta, fácil es relativo a la persona.</p><p>Les recomiendo ver la charla “<a href="http://www.infoq.com/presentations/Simple-Made-Easy">Simple Made Easy</a>” de Rich Hickey, que aborda este tema en mucho mayor detalle, y es una de las mejores<br>charlas de ingeniería de software que he visto.</p><h4>Interfaz</h4><p>En el contexto de responsabilidad hacia nuestros usuarios, hablemos de la interfaz. Yo se que la mayoría acá somos programadores y no diseñadores, pero es muy importante aprender algunas cosas de diseño de UI para evitar papelones y hacer algo que el usuario no sufra usando.</p><p>Queremos que la interfaz sea simple y se sienta fácil. O sea, que no tenga demasiadas cosas a la vez, pero además, que las que tenga se sientan familiares para nuestros usuarios.</p><p>Lamentablemente la mayoría de nosotros somos programadores, no diseñadores, y los programadores somos notoriamente malos diseñando interfaces. ¿Cómo podemos, entonces, ser responsables hacia nuestros usuarios y brindarles una interfaz fácil y simple?</p><p>Podríamos hablar durante horas de esto, y lamentablemente no nos da el tiempo, pero por suerte otra gente ha hecho el trabajo duro y ha dado buenas charlas al respecto. Un par que podrían mirar son:</p><ul><li><a href="http://www.confreaks.com/videos/522-roa2011-design-hacks-for-the-pragmatic-minded">Design hacks for the pragmatic minded</a> por Kyle Neath</li><li><a href="https://www.youtube.com/watch?v=kk3o92RZbw0">I Am Designer and So Can You!</a> por Justine Arreche</li><li><a href="https://www.youtube.com/watch?v=iRfoKdRgZdU">The Rubyist’s Guide to Design</a> por Julie Ann Horvath</li></ul><p>Lo importante es que aprender un poco de algunas cosas de diseño nos da una buena base para hacerle la vida a los usuarios más placentera. Sin embargo, no hay que pretender saber <em>TODO</em> lo que hay para saber de diseño. Incluso aprendiendo técnicas básicas, no vamos a crear interfaces maravillosas siempre. ¿Cómo hacemos, entonces?</p><p>¡Molesten a un diseñador! No muerden, lo prometo. Pídan ayuda. Trabajen con alguno. ¡Es su responsabilidad molestar un diseñador! No tienen que saber todo de <strong>todo</strong>. Es mejor conseguir ayuda de otros y complementarse.</p><h4>Performance</h4><p>Esto es parte del <a href="https://dribbble.com/shots/808470-The-Zen-of-GitHub">Zen of GitHub</a>, una serie de máximas sobre cómo escribir software con la “filosofía” de GitHub:</p><blockquote>It’s not fully shipped until it’s fast.<br>Responsive is better than fast.</blockquote><p>A qué viene esto? Nuestra responsabilidad es entregar software que funciona bien. Algo que funciona lento no funciona. Punto.</p><p>Pero más allá de que algo <em>sea</em> rápido, lo importante es que se <em>perciba</em> como rápido. Esto es, no importa si algo demora 5 segundos en cargar, si la UI nunca demora más de unos pocos milisegundos en refrescarse y mostrar cambios en el estado.</p><p>Un claro ejemplo de esto es por qué haciendo aplicaciones web ponemos los javascripts al final del documento y no en el <em>&lt;head&gt;</em>. Cuando los browsers evalúan javascript entran en single threaded mode, por lo que evaluar un JS requiere que el browser deje de cargar el HTML, el CSS, y renderizar el markup en pantalla. Si de repente tiene que evaluar 200 Kb de javascript que se encuentran en el <em>&lt;head&gt;</em> (el cuál se evalúa antes de que se empiece a mostrar contenido), quiere decir que va a tener que pausar por 50–100 ms en los cuales el usuario va a ver una página en blanco sin nada y sin actividad.</p><p>El tiempo <strong>total</strong> de carga es el mismo. Pero poniendo los JS al final el usuario no <strong>percibe</strong> la demora inducida por evaluar el JS.</p><p>Una vista demora mucho en generarse? Carguen una versión inicial con un spinner y hagan push del contenido al cliente (o hagan polling si no pueden usar push), y muestren el contenido a medida que lo tengan disponible.</p><p>Lo importante es que el usuario nunca puede quedarse esperando en un lugar donde no puede interactuar con sus alrededores.</p><p>Ojo! La performance es quizás el trait más importante en el software que producimos (después de que funcione como debe, claro), pero esto no quiere decir que haya que salir a optimizar cada línea de código. Knuth nos dice, en su paper <a href="http://cs.sjsu.edu/~mak/CS185C/KnuthStructuredProgrammingGoTo.pdf">Structured Programming with Go To Statements</a>:</p><blockquote>Premature optimization is the root of all evil.</blockquote><p>“La optimización prematura es la raíz de todos los males.”</p><p>El código tiene que ser mantenible y entendible. Cambiar todas las divisiones a bitwise operations porque ahorra ciclos de CPU no otorga una mejora medible en general (salvo, quizás, que estén trabajando en embedded appliances o en un marcapasos o algo así—pero por favor, no usen ruby en un marcapasos).</p><p>Ante la duda, las <strong>únicas</strong> mejoras de performance que importan son las que el usuario va a percibir. Cualquier cosa que no sea <em>medible</em>, no necesita ser optimizada.</p><h3>Responsabilidad con nuestros pares</h3><p>Bueno, hablemos un poco de la responsabilidad hacia nuestros compañeros. En mi primer trabajo programando, un amigo me dijo la máxima de vida más útil relativa a la programación que escuché:</p><blockquote>Tenés que programar como si la persona que vaya a mantener tu código en seis meses es un psicópata homicida que sabe dónde vivís.</blockquote><p>Lo que queremos, entonces, para evitar psicópatas asesinos, es que nuestro código sea fácil de mantener.</p><h4>Mantenibilidad</h4><p>El concepto de “mantenibilidad” es un poco difuso, quizás, así que tratemos de acotarlo un poco. Vamos a decir que código mantenible es código:</p><ul><li>Legible</li><li>Claro</li><li>Comprensible</li><li>Modificable</li></ul><h4>Claridad y Prolijidad</h4><p>Nuestro trabajo involucra mucho más lectura de código que escritura de código. El código que Uds. escriben hoy lo van a leer Uds. mañana, sus compañeros pasado mañana, y otros psicópatas homicidas en seis meses.</p><p>Es importante que el código sea legible. Es importante que el código esté bien indentado, y que siga las normas de estilo de tu empresa o comunidad.</p><p>Para que el código sea claro, además, tiene que ser directo. Tiene que ser sucinto y terso, para reducir las distracciones al leerlo.</p><pre>10.times { puts &quot;hi&quot; }</pre><p>vs</p><pre>i = 0<br>while i &lt; 10<br> puts &quot;hi&quot;<br> i += 1<br>end</pre><p>El primer snippet es <em>inmediatamente comprensible</em> por dos motivos:</p><ol><li>Menos código—volvemos a la simpleza. El <em>código más simple</em>, al tener menos partes, se puede comprender más rápido.</li><li>Está más cerca del lenguaje natural con el que expresamos nuestras ideas. Uno naturalmente diría “Quiero decir esta palabra 10 veces”. Uno nunca diría “Quiero tener cero dedos levantados, e ir levantándolos de a uno; y por cada vez que levanto uno, decir esta palabra, hasta que tenga 10 dedos levantados y ahí callarme la boca”. Al estar más cercano al lenguaje con el que nos expresamos, <em>es más fácil</em> para nosotros.</li></ol><p>Ruby es un excelente lenguaje para escribir código que se acerque bastante al lenguaje natural, es un lenguaje que nos permite ser tersos y sucintos. Y que nos permite escribir código que se lee <em>casi</em> como lenguaje natural.</p><p>Podemos, también, escribir código para generarnos un metalenguaje arriba de ruby que se lea tal cual como lenguaje natural. A mucha gente le encanta hacer estas cosas (<em>ahem</em> <a href="http://rspec.info/">RSpec</a> <em>ahem</em>).</p><p>¡Ojo! El que podamos hacer algo no quiere decir que debamos. Cuando decidamos escribir algo de código “mágico”, preguntémonos “¿Debo?”. La respuesta es casi siempre un rotundo “No”.</p><p>¿Por qué? El código “mágico” es en general mucho más complicado de mantener. Hay que encontrar un balance entre legibilidad y cercanía al lenguaje natural, considerando siempre con mucho cuidado las decisiones que tomamos que puedan afectar la mantenibilidad del código.</p><p>Si bien el primer snippet es inmediatamente más comprensible, internamente <em>Integer#times</em> <a href="http://ruby-doc.org/core-2.1.2/Integer.html#method-i-times">está implementado</a> de una forma muy similar al segundo snippet (aunque en C, no en ruby).</p><p>Crear estos metalenguajes—DSLs (“Domain Specific Languages”), implica agregar un nivel más de abstracción a nuestro código. Tenemos que evaluar siempre hasta qué punto la complejidad agregada vale la mayor legibilidad.</p><p>Lamentablemente no hay una respuesta única y absoluta. Como mucho en la vida, es un <em>tradeoff</em> que hay que sopesar durante el desarrollo.</p><p>¿Qué beneficios <strong>reales</strong> trae a la mantenibilidad a largo plazo de este código agregar este nivel extra de indirección?</p><h4>Documentación</h4><p>El código sucinto y terso suele ser comprensible, pero aún así es muy importante documentar lo que hacemos. No me refiero comentar cada línea de código—no, para eso es que tenemos que escribir código claro.</p><p>Me refiero a documentar—en una o dos líneas nomás—el propósito de los métodos, qué se supone que son los parámetros, y qué devuelve.</p><p>Las interfaces que escribimos en nuestros programas—interfaz en el sentido Java-esco—son primordialmente para manipular abstracciones. Es necesario que alguien nuevo (o alguien que no se acerca a ese rincón del código hace un tiempo) pueda tirarse a modificar algo y entender cuáles son las abstracciones en juego.</p><p>Hay, sin embargo, un par de cosas a tener en cuenta con la documentación. La documentación está pensada—antes que nada—para leerla cuando lees código. Eso quiere decir que, primero que nada, tiene que estar dirigida a humanos.</p><p>No hace falta inventarse todo un lenguaje nuevo con <em>tags</em> y gramática y otras convenciones que haya que aprender. Ojo, no estoy diciendo que esto esté mal, si todos en tu equipo están familiarizados con la gramática de una herramienta como <a href="http://yardoc.org/">YARD</a>, me parece excelente que la usen.</p><p>Mi punto es que nuestra responsabilidad es documentar el código para que nuestros compañeros (o incluso nosotros mismos) podamos volver a él y entender qué intenciones teníamos cuando lo escribimos. Para cumplir con esta responsabilidad, tenemos que reducir la barrera de entrada a escribir documentación lo más posible.</p><p>En general en los equipos en los que he trabajado trato de promover usar algo parecido a <a href="http://tomdoc.org/">TomDoc</a>. Ni siquiera me esfuerzo demasiado porque sea TomDoc estrictamente—no necesitamos generar documentación fuera del código, ya que este tipo de documentación es para cuando leemos código nomás, por lo que no es particularmente interesante en general que esto se apegue a una sintaxis con demasiado cuidado.</p><p>Lo que sí es importante es que ese par de líneas que tenemos ahí que me dicen por qué está ese método, qué son los parámetros que recibe, y qué se supone que devuelva sean legibles y claros. Sus “yo” de dentro de 6 meses van a agradecer que se tomaron esos 3 minutos para documentar el código.</p><p>Lo otro importante sobre escribir documentación es mantenerla actualizada. Es horrible encontrarse con algo documentado y creerle a la documentación, solo para descubrir que esa documentación es pura mentira.</p><p>Por ejemplo, hace unos meses estaba trabajando en un proyecto bastante complejo, y tenía a un amigo trabajando conmigo. Mi amigo tenía que debuggear un problema con un proveedor externo. Le dijeron “las credenciales para hacer login con este proveedor las podés encontrar en X página de la wiki”.</p><p>Una tarde, muchas lágrimas y un montón de pelo arrancado después, alguien más del equipo lo ve en el chat puteando porque no puede hacer login con las credenciales que encontró en la wiki, y le dice “Jeje, no, no. Para ese servicio lo que está en la wiki no sirve, tenés que usar estas otras credenciales”.</p><p>*facepalm*</p><p>Una forma simple de remediar esto es mantener la documentación cerca del código. Y cuando digo cerca, me refiero a <strong>en</strong> el código. Es mucho más fácil decir en un Pull Request “no, no mergees este feature nuevo hasta no actualizar toda la documentación de las cosas que cambiaste” que decir “ah, ahora después de mergear esto, acordate de ir a la wiki y cambiar cosas”.</p><p>Con los “API docs”, que describen los métodos, esto no es un problema (o al menos es uno mucho más simple de resolver), porque solemos escribir la documentación de esos métodos en el código junto a ellos. El problema se presenta cuando queremos tener documentación más generica.</p><p>Quizás de procesos o explicando ciertos flujos que son específicos a la app. Por ejemplo el setup (más sobre esto luego), o explicando la arquitectura a alto nivel, o cómo se integra esta aplicación con otras cosas.</p><p>Para esto, mucho mejor que una wiki es tener una carpeta <em>docs/</em> en el código, donde ponemos archivos en algún formato que nos guste—como puede ser markdown o RST o similar. Ahora es mucho más fácil al ver el diff de un Pull Request si la documentación pertinente se actualizó junto con el código.</p><h4>Bootstrapping</h4><p>Hablando del setup de un proyecto, otra cosa en la que vale ser responsables con nuestros pares es en no hacerlos sufrir mucho para poder empezar a trabajar en el proyecto.</p><p>El proceso de qué hay que instalar—qué versiones de servicios como Postgres, en qué puertos espera el proyecto que las cosas estén corriendo, o dónde configurar estas cosas, tiene que estar claramente documentado. Preferiblemente en el README del proyecto, o linkeado desde ahí si resulta ser muy largo.</p><p>Pero mejor aún que documentarlo, podemos automatizar mucho de esto. Una combinación de buenos defaults en la configuración, y de scripts que se ocupen de chequear dependencias o inicializar lo necesario para que la aplicación corra hacen maravillas a la hora de traer gente nueva al proyecto.</p><p>Por ejemplo, suelo poner en mis proyectos dos scripts:</p><ul><li><em>script/check</em> que se asegura que las dependencias externas estén instaladas, como son PostgreSQL, Redis, o memcached. Si encuentra problemas, te dice cómo arreglarlo (si hay que instalarlos, o si hay que configurar la app para encontrar estos servicios en otro puerto, por ejemplo).</li><li><em>script/bootstrap </em>se asegura de que las gemas estén instaladas, y las bases de datos tengan el esquema correcto y migrado a la última versión. Además, este script guarda un checksum de la lista de gemas, por lo que si no modificamos nuestro <em>.deps</em> o <em>Gemfile.lock</em> no va a tratar de instalar gemas (lo cual puede ser lento, si usan algo como Bundler). Y si no cambió su schema de la base de datos, tampoco va a tratar de hacer migraciones. O sea: cuando no hay nada que hacer, termina en apenas un par de milisegundos, lo cual nos permite llamar este script desde el script que corre los tests, o que abre la consola, o que inicia el server.</li></ul><p>Con estos dos scripts ahí, una persona nueva que llega al proyecto lo único que tiene que hacer es correr <em>script/check</em>, instalar cualquier cosa que le diga que falta, correr <em>script/check</em> para ver que ahora todo está bien, y luego <em>script/server</em> (que internamente llama a <em>script/bootstrap</em>). Et voilà! Tiene el proyecto corriendo.</p><p>Hablando de defaults inteligentes, la noción de no versionar sus archivos de configuración es medio tonta. El <em>.env</em> que guarda todas las variables de entorno que queremos usar para la app (como la URL de la base de datos o de redis, o la configuración para mandar mails) está versionado, y tiene valores que para la configuración por defecto de las distintas cosas deberían ser suficientes. Por ejemplo:</p><pre>DATABASE_URL=postgres://${PGUSER}@${PGHOST}:${PGPORT}/some_db<br>REDIS_URL=redis://127.0.0.1:6379<br>SESSION_SECRET=deadbeef</pre><p>Ahora cualquier persona que inicie la app—si tiene los servicios instalados en los lugares normales y corriendo en los puertos normales, no tiene que hacer absolutamente nada para correr la app.</p><p>A esto se suma otro archivo—también versionado—que se llama <em>.env.test</em> con los overrides que haya que hacer para los tests. Por ejemplo:</p><pre>DATABASE_URL=postgres://${PGUSER}@${PGHOST}:${PGPORT}/test_db<br>REDIS_URL=redis://127.0.0.1:6379/5</pre><p>Noten que no es necesario definir todas las variables de nuevo. Solo tenemos que cargar el archivo de test después del de development, y sobre escribir cualquier variable que tenga que cambiar.</p><p>¿Y qué pasa cuando alguien tiene alguna configuración particular en su environment local? Ahí sí queremos un archivo que no esté versionado donde cada uno pueda hacer lo que quiera para configurar “las cosas raras”. Algo como <em>config/personal.rb</em> donde podamos manipular el environment libremente para setear configuraciones personales. (<em>script/check</em> se asegura de avisarte que como no pudo encontrar X servicio en donde lo espera, deberías configurarlo en tu <em>config/personal.rb</em>). Por ejemplo:</p><pre># I run Postgres in a VM because I rebel against the system<br>ENV[&quot;DATABASE_URL&quot;] = &quot;postgres://172.109.10.1/some_db&quot;</pre><pre>if ENV[&quot;RACK_ENV&quot;] == &quot;test&quot;<br>  ENV[&quot;DATABASE_URL&quot;].gsub!(&quot;some_db&quot;, &quot;test_db&quot;)<br>end</pre><p>Este esquema de configuración es simple, flexible, y permite tener defaults que funcionan y que hacen que la gente no tiene que preocuparse en perder tiempo haciendo andar la aplicación cuando recién comienza con ella. En lugar de estar 3 horas para levantar la app la primera vez, estás 5 minutos. O si tuviste que instalar algún servicio como redis, quizás 15 minutos. Pero <em>nuestra aplicación</em> no es el punto de sufrimiento.</p><p>Eso es algo que podemos—debemos—hacer por nuestros compañeros.</p><h4>Simpleza</h4><p>A los rubyistas nos encanta estar en el Bleeding Edge. Nos encanta ordenar las gemas por versión de última actualización, e incluso penalizamos a las librerías que hace mucho no se actualizan como “menos recomendadas para usar en producción”.</p><p>Supongamos que tengamos que usar una herramienta, vemos de cuándo es la última versión, y nos encontramos con que es del 2002.</p><blockquote>Ewww, ¡2002! Eso está RE sin mantener. Seguro que debe estar llena de bugs y voy a tener que lidiar con toda la mierda de los developers irresponsables que hace más de 10 años no sacan una versión nueva. Nope, paso, voy a buscar otra forma de hacerlo.</blockquote><p>A todos se nos pasó por la cabeza algo como esto en algún momento. Ahora, ¿qué pasa si les digo que esta herramienta del 2002 es <em>ls(1)</em>? La versión de <em>ls</em> que viene en OS X es del 2002. Seguramente haya versiones más viejas en otros unixes actuales.</p><p>¿Qué hacemos, entonces? ¿No usamos <em>ls</em> para listar archivos porque hace más de 10 años que nadie la actualiza?</p><p>Claro que no. Usamos <em>ls</em> porque funciona. Hace 12 años que <em>ls</em> no se actualiza, no por no estar mantenido, sino porque <strong>funciona</strong>. Las herramientas del toolchain de UNIX, en su gran mayoría, reciben muy pocos updates. Y funcionan a la perfección.</p><p>¿Qué comparten en común, que las hace tan robustas?</p><p>Su simpleza.</p><p>Todas las herramientas del toolchain de UNIX hacen una sola cosa, y la hacen bien. ¿Se acuerdan de “sem-plex”? ¿Una cosa sola? Esta simpleza hace que las herramientas sean increíblemente robustas.</p><p>Herramientas simples, pequeñas, con un scope acotado, y con una interfaz común que permita componerlas para lograr sistemas complejos son la clave a sistemas robustos y mantenibles.</p><p>Mañana tenemos la charla de Michel sobre este tema, así que no quiero estar horas hablando de esto, pero sí quiero recalcar el punto:</p><p><strong>Concéntrense en escribir software simple.</strong> Del software simple se desprende la mantenibilidad. Software simple que además está escrito claramente y bien documentado hace que nuestros compañeros puedan trabajar con él sin problemas. Sin sufrir. Sin convertirse en psicóticos asesinos en unos pocos meses.</p><h4>Responsabilidad con nosotros mismos</h4><p>La última responsabilidad que tenemos es para con nosotros mismos. Tenemos que entender que lo que hacemos no lo hacemos para nosotros, lo hacemos para TODO el mundo. Cuando escribímos código estamos afectando a todos los potenciales consumidores del resultado de nuestro código. Tenemos, entonces, que hacer lo mejor para TODOS—no lo mejor para nosotros.</p><p>Cuando nos sentamos a escribir software, es importante que pensemos en cómo los usuarios van a interactuar con nuestro programa. Somos responsables de tratar de ponernos en sus zapatos y hacer lo mejor que podamos para ellos.</p><p>Es importante que nos pongamos en los zapatos de nuestros pares, quienes van a tener que lidiar con todas nuestras cagadas en el futuro. Somos responsables de que no sufran demasiado, así como a nosotros nos gusta no sufrir demasiado con el código con el que trabajamos hoy.</p><p>Somos responsables de hacer del mundo un lugar mejor.</p><p>Gracias.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=fd0237bf1a21" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>