Sobre como evolucionar un API

Posted by Aitor García Wed, 28 Sep 2005 06:43:00 GMT

El siempre brillante Sam Ruby se encuentra portando el software de su blog a Ruby (que metafísico ¿verdad?) y en el camino se ha encontrado solventado bugs que existen dentro de la plataforma. En concreto generando la fuente atom para su sindicación se ha percatado que solo los valores de los elementos se estaban escapando en el XML builder de Ruby. En el caso de los atributos no se estaban escapando en modo alguno. Asi, el siguiente codigo produce resultados un tanto inconsistentes:
xml.title('1<2') => <title>1&lt;2</title>

@xml.a(:title => '1<2') => <a title="1<2"/>

El tema es que Sam ha realizado un parche que ilustra muy bien la naturaleza abierta en runtime de las clases en Ruby.

Por instructivo y pedagogico que resulte todo esto no es el punto al que me quiero referir en el post. Casualmente Jim Weirich, que mantiene esta libreria, la habia actualizado el fin de semana anterior porque otra persona se habia percatado del mismo bug. El software estaba corregido en el CVS. Curiosamente el enfoque que habia tomado Jim no era el que yo (y parece que tampoco Sam) esperaba:
 xml = Builder::XmlMarkup.new(:escape_attrs => true)
¿Por qué introducir el arreglo como un atributo opcional?. Pues Jim lo explica:

An early user of builder was using entities explicitly in attribute values. Escaping attribute values would make that use very difficult. On the flip side 99% of the users don’t care about that use case, so that was probably a bad call early on.

Y aqui es donde queria llegar. Sam en otro comentario aporta unos razonamientos excelentes sobre cómo y por qué tomar decisiones en la evolución de un API:

Several counterpoints:
  • This just moves the problem. Rails automatically instantiates the builder object, and generally eschews configuration. Requiring configuration for an option that 99% of the users will want (or equivalently — will be prone to error if not set) just doesn’t make good sense.
  • Apparently, the API changed for builder 1.0, so there is precedent for making incompatible changes.
  • As was previously stated, 99% of the users would find it surprising if they were told that they were responsible for escaping — but only in the case of attributes. Most of these people won’t notice the change, except for the fact that the documents that they produce are not only more often well formed, but also that these documents actually convey the information that they expect.
  • The users that expect to have control over escaping are more likely to have unit tests that will fail if the default changed – and therefore, would more likely be in a better position to react (i.e., discover and make the one line change).

  • Net: in real life, I tend to find that there are rarely any absolutes. Every bug is potentially a feature, and therefore every bug fix is potentially a breaking change. That doesn’t mean that bug fixes shouldn’t be made. Both builder and rails are comparatively young and — at the moment at least — fairly free from the cruft that this option is an example of. Three years from now, is this the way we all would like to see this API look?

Finalmente Jim ha aceptado que las argumentaciones de Sam son acertadas e introducirá el arreglo dentro del funcionamiento por defecto del XML Builder. Todo un ejemplo del buen hacer de dos monstruos del mundo del Open Source que toman las decisiones adecuadas con esa herramienta tan devaluada hoy en dia que se llama diálogo.

Trackbacks

Use the following link to trackback from your own site:
http://fco.textdriven.com/articles/trackback/157

Comments

Leave a response

Comments