Conoce el nivel de indentación del texto con VoiceOver de forma automática

VoiceOver para MacOS es incapaz de conocer y notificar el nivel de indentación del texto. Por esa razón en su día desarrollé un script que puede averiguar y verbalizar esta información. 

Este script está disponible en el repositorio de Indentation line for VoiceOver.

Usando el script manual

En este repositorio está el fichero speakIndentationLine que contiene el AppleScript para que VoiceOver verbalice el nivel de indentación del último texto verbalizado por el lector de pantallas.

Este script debía asociarse a un atajo de teclado de VoiceOver para poderlo utilizar de forma cómoda pero incluso así existía la posibilidad de perdernos un cambio de indentación debido a que debíamos revisar manualmente cada línea de un texto para conocer si había algún cambio en el nivel de indentación.

Automatizando la funcionalidad

Para solucionar el problema se ha creado un nuevo script en el repositorio llamado checkIndentationService que ejecuta la función de verificar el nivel de indentación de forma automática y sólo se verbaliza cuando se han producido cambios en el nivel de indentación.

Para que este script se ejecute de forma apropiada es necesario exportar el script como aplicación y asegurarnos que en la conversión esté marcada la opción Permanecer abierto tras el gestor de ejecución. Puedes leer sobre el proceso en el artículo Convertir un AppleScript en una aplicación para MacOS.

Una vez convertido tendremos la opción de abrir la aplicación checkIndentationService y VoiceOver verbalizará cada nuevo cambio de nivel de indentación de un texto.

Recuerda leer el fichero Readme.md del repositorio para saber cómo cambiar la voz que se utiliza para hacer las notificaciones.

Código limpio con comentarios útiles

Un código con buenos comentarios ayuda a su legibilidad como vimos en el artículo sobre cómo escribir código limpio y legible.

Cada bloque de código tiene un propósito, puede recibir parámetros y puede devolver un resultado. Toda esta información debería estar explicada brevemente en un bloque comentado, preferentemente antes de los bloques de ejecución. Por ejemplo:

// Función calculaPrecioFinalDeCarrito

//    Calcula el precio final del carrito ajustando impuestos y conversión de moneda

//

// Entrada:

//    lista de productos, tipo de impuestos, tipo de moneda

// Salida:

//    precio final a pagar por el cliente

function calculaPrecioFinalDeCarrito(listaProductos, tipoDeImpuestos, tipoMoneda) {

    var precioSinImpuestos = calculaPrecioDeListaDeProductos(listaProductos)

    var precioConImpuestos = calculaImpuestos(precioSinImpuestos, tipoDeImpuestos)

    var precioFinal = convierteAMoneda(precioConImpuestos, tipoMoneda)

    return precioFinal

}

Pero se debe ser breve y evitar comentar todo lo que hace el código línea a línea explicando sólo lo esencial.

Se debe explicar el porqué de las cosas y no cómo se hacen. Un buen código se da a entender por sí solo y no necesita extensos comentarios para ello.

Consistencia y legibilidad para un código limpio

En el artículo sobre cómo escribir código limpio y legible hablamos de la necesidad de coherencia cuando escribimos código.

Legibilidad por encima de la simplicidad

Algunos lenguajes de programación permiten realizar varias operaciones en una sola línea de código. Por ejemplo en Swift, Java o C++ podemos crear una instancia de clase, llamar a uno de sus métodos y realizar una comparación dependiendo del resultado de esa llamada todo en una sola línea de código. Esto reduce el número de líneas que pueda tener una función pero no mejora la legibilidad del código ya que quizás esas características del lenguaje de programación no son conocidas por todos los programadores.

Recuerda escribir el código para que lo pueda leer otra persona, porque incluso hay altas probabilidades que esa otra persona seas tú y puede que no entiendas tu propio código pasado unos meses o años.

Consistencia en la arquitectura de un proyecto

Una de las decisiones principales a tomar cuando empezamos un proyecto software es la de qué patrón de diseño utilizaremos para la arquitectura de nuestra aplicación.

Una vez tomada esta decisión debemos evitar mezclar arquitecturas ya que aumentamos la complejidad a la hora de entender cómo se organiza nuestro proyecto.

Código limpio sin código inutil

En el artículo sobre cómo escribir código limpio y legible hablamos de la necesidad de un código que no tenga bloques de código inútil.

Estos bloques de código inútil se originan normalmente cuando estamos probando un código de forma temporal para hacer un experimento en nuestro proyecto.

Activando y desactivando bloques de código

Dentro de un proyecto de software puede que durante una ejecución de prueba controlada nos interese desactivar un bloque de código y activar otro. Esto se consigue gracias a las instrucciones para añadir comentarios en un código.

Cada lenguaje de programación posee uno o varios métodos para comentar un trozo de código. Por ejemplo la función original sería:

Funcion calcularImpuesto() {

    calcularImpuestosDelCarrito()

}

Y para nuestro experimento quedaría así:

Funcion calcularImpuesto() {

    // Comentamos la siguiente línea para la prueba

    // calcularImpuestosDelCarrito()

    // Usamos el experimento

    calcularImpuestosDelCarritoDeOtraForma()

}

El problema

El problema aparece cuando dejamos esos comentarios porque nos ha gustado más el resultado de la prueba. El código resultante está lleno de bloques inútiles que dificultan la lectura del código.

La solución consiste en quitar esos bloques de código y dejar sólo el código útil. El ejemplo quedaría al final así:

Funcion calcularImpuesto() {

    calcularImpuestosDelCarritoDeOtraForma()

}

¿Cómo no perder esos bloques comentados?

Puede que para nuestro proyecto nos interese no perder ese código alternativo que al principio estaba desactivado con comentarios y que posteriormente borramos para mejorar la limpieza de nuestro código.

Para evitar perder este código alternativo lo mejor es utilizar un sistema de gestión de versiones de código como Git o Mercurial.

Con estas herramientas podemos tener varias versiones de nuestro proyecto e ir manteniendo el código límpio en todo momento sin perder nada ya que con la herramienta de gestión de versiones podemos consultar código más viejo en cualquier momento.

Funciones simples para un código limpio

En el artículo sobre cómo escribir un código limpio y legible hablamos de la necesidad de escribir funciones simples y cortas.

Esto se debe a que a la hora de leer código de otra persona si una función es demasiado larga y posee muchas líneas de código es muy probable que perdamos el foco de atención. Además eso puede significar que la función está realizando demasiadas tareas y debemos atomizar nuestro código.

Código atomizado

Una función con código atomizado tiene un propósito y no puede reducirse o simplificarse mas. Cuanto más simple sea nuestra función más claro será nuestro código.

Por ejemplo una función llamada calcularAlmacenajeDeSucursales puede dividirse en varias funciones más pequeñas que calculen el resultado que estamos buscando en nuestra función inicial.

Dividiendo una función en varias funciones más pequeñas conseguimos atomizar nuestro código y mejorar su legibilidad.

Nombres claros para un código limpio

Como vimos en el artículo sobre cómo escribir código limpio y legible el utilizar nombres claros y explícitos para nombrar variables, constantes, funciones y clases es indispensable para considerar que tenemos un código limpio y legible.

Variables y constantes

A la hora de poner nombre a una variable o constante debemos pensar en que nuestro código lo puede leer otra persona y tendrá qué entender que hace nuestro código. Una variable llamada aux, A, contar o num no aclara qué hace un código pero nombres como hipotenusa, precioFinal, distanciaDelMargen o ContadorDePalabras si son nombres más comprensibles para todos.

Funciones y clases

A la hora de poner nombres a métodos y clases debemos prestar atención al trabajo o responsabilidad que realizan. Nombres de clases como ControlDeDatosDeUsuario, VisualizadorDeDatosDeUsuario, DriverDeDatosDeUsuario son nombres apropiados para entender qué hace una clse.

En el caso de las funciones o métodos el nombre debería describir la función que se va a realizar. Nombres como GuardarDatosDeUsuario, CargaDatosDeUsuario o BorraUsuario son nombres bastante explícitos para entender qué hará la función al ser llamada.

Coherencia a la hora de escribir los nombres.

Hay varios métodos para escribir nombres de variables, métodos y clases como el método Camel case, el Pascal case o la notación Húngara.Podemos seguir cualquiera de estos métodos de escritura de nombres pero lo que no debemos hacer es mezclarlos en un mismo proyecto ya que hace que nuestro código sea confuso de entender y mantener.