Guía de estilo de Exercism

Este documento sirve de guía de estilo para el lenguaje y la redacción que se emplean en los ejercicios.

Aplicación

Estas reglas deben seguirse en todos los ejercicios. Las descripciones y los casos de prueba existentes pueden actualizarse para cumplirlas sin necesidad de crear casos de prueba «de reemplazo».

Coherencia dentro de un ejercicio

Hay algunos términos que admiten varias grafías válidas (p. ej. «lower case» frente a «lowercase»). Cuando este documento no fije un estilo concreto, esos términos deben usarse de forma coherente dentro de un mismo ejercicio.

Excepciones

Los ejercicios pueden apartarse de estas reglas si existe un consenso general entre sus mantenedores de que es razonable. Por ejemplo, un ejercicio sobre la conversión entre distintas unidades podría optar por no usar medidas del SI.

Lenguaje

Todo el contenido debe escribirse en inglés estadounidense, que se diferencia del inglés británico en multitud de aspectos. En el futuro puede que haya otras traducciones, pero el idioma «oficial» de Exercism es el inglés estadounidense.

Medidas

Todas las unidades de medida deben ser unidades del SI o derivadas del SI.

Abreviaturas, acrónimos y siglas

Las abreviaturas, los acrónimos y las siglas suelen ser más difíciles de entender que otras opciones de redacción, y pueden distanciar a quienes están intentando aprender.

Muchas abreviaturas son jerga. Evita la jerga siempre que puedas usando otras formas de expresarte. No uses abreviaturas a menos que se cumpla alguna de estas condiciones:

  • La forma abreviada se conoce mejor que la forma completa
  • El texto resultaría excesivamente verboso sin la abreviatura

Cuando uses abreviaturas, explica siempre qué significa el término la primera vez que aparezca. A menudo, aunque no siempre, esto consistirá en desarrollar la abreviatura. Rara vez bastará con limitarse a desarrollarla.

Estos son algunos ejemplos de reglas:

  • Prefiere «if I recall correctly» a «IIRC»
  • Prefiere «as far as I know» a «AFAIK»
  • Prefiere «queue» a «FIFO» y «stack» a «FILO»
  • En lugar de describir una interfaz como «RESTful», describe sus propiedades concretas
  • Si tienes que usar «CRUD», explica que son las iniciales de Create, Read, Update, Delete y que estas son las acciones básicas de las bases de datos estándar

Y algunos ejemplos de buen uso:

  • «HyperText Markup Language (HTML) is the language used to describe document structure and content on the web» (ampliado y explicado)
  • «DNA, a set of chemical instructions that influence how our bodies are constructed» (DNA no se desarrolla porque es poco probable que «deoxyribonucleic acid» ayude a explicar a nuestro público qué es el DNA)
  • «NASA, the United States' space agency, launched the Mariner 2 space probe in...» (NASA no se desarrolla porque «National Aerospace and Space Administration» se conoce mucho mejor por sus siglas que por su nombre desarrollado)
  • «The Department of Motor Vehicles (DMV) is filled with sloths. That's why everything takes forever at the DMV» (Define DMV la primera vez que se usa)

Gramática

La coma de Oxford

Usa la coma de Oxford (también conocida como coma serial) en las enumeraciones. Por ejemplo, en lugar de «I love my parents, Lady Gaga and Humpty Dumpty», escribe «I love my parents, Lady Gaga, and Humpty Dumpty». También puede gustarte esta imagen a modo de explicación.

Excepciones

Hay algunas abreviaturas que consideramos lo bastante comunes, útiles y poco técnicas como para permitirlas:

  • e.g. o eg
  • i.e. o ie
  • etc. o etc
  • docs

Las contracciones (p. ej. «won't», «I'm», «that's») deben usarse con moderación, si es que se usan, en las descripciones de los ejercicios, pero no están restringidas en el resto del texto del sitio (p. ej. los textos de la web, la mentoría).

Muchas guías de estilo del inglés estadounidense indican que a las abreviaturas «i.e.» y «e.g.» les debe seguir una coma (véase, p. ej., este hilo de StackExchange). Esto está permitido, pero no es obligatorio en los textos de Exercism.

Elección de palabras

Términos matemáticos y jerga

Siempre que se usen términos matemáticos, deben explicarse o sustituirse por términos que exijan menos conocimientos especializados.

Ejemplos:

  • En lugar de usar «natural numbers», deberíamos usar «positive whole numbers».
  • Si queremos usar la expresión «rational numbers», hay que explicarla en la introducción del ejercicio.
  • En lugar de usar la palabra range (que puede tener significados distintos según el contexto), usa «x < ? < y (greater than x and less than y)».
  • En lugar de usar «esoteric terms», usa la expresión «terms not understood by the majority of people».

Código

Todo el código debe tener un formato coherente que siga las convenciones de estilo de su track. Cuando sea posible, esas convenciones de todo el track deberían coincidir con las convenciones de estilo preferidas del lenguaje.