Guía de estilo de Exercism

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

Aplicación

Estas reglas se deben seguir en todos los ejercicios. Las descripciones y los casos de test existentes se pueden actualizar para cumplirlas sin necesidad de casos de test de «reemplazo».

Consistencia dentro de un ejercicio

Hay términos que tienen varias grafías válidas (p. ej., «lower case» frente a «lowercase»). Cuando en este documento no se haya acordado un estilo consistente, estos términos deben mantenerse consistentes dentro de un ejercicio.

Excepciones

Los ejercicios pueden apartarse de estas reglas si hay consenso general entre los mantenedores de que eso es razonable. Por ejemplo, un ejercicio sobre convertir entre distintas unidades podría optar por no usar medidas del SI.

Idioma

Todo el contenido debe escribirse en inglés estadounidense, que se diferencia del inglés británico de diversas maneras. 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 del SI o derivadas del SI.

Abreviaturas, siglas y acrónimos

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

Muchas abreviaturas son jerga. Evita la jerga siempre que sea posible usando otras palabras. No uses abreviaturas a menos que se cumpla alguna de estas condiciones:

  • El término abreviado sea más conocido que el término sin abreviar
  • El texto quede excesivamente extenso sin la abreviatura

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

Aquí tienes algunas reglas de ejemplo:

  • Prefiere «if I recall correctly» en lugar de «IIRC»
  • Prefiere «as far as I know» en lugar de «AFAIK»
  • Prefiere «queue» en lugar de «FIFO» y «stack» en lugar de «FILO»
  • En lugar de describir una interfaz como «RESTful», describe sus propiedades específicas
  • Si tienes que usar «CRUD», explica que son las siglas de Create, Read, Update, Delete y que 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» (se desarrolla y se explica)
  • «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 qué es el DNA a nuestro público)
  • «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 más 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

Coma de Oxford

Usa la «coma de Oxford» (también conocida como coma serial) en las listas. 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 que lo explica.

Excepciones

Algunas abreviaturas se consideran lo bastante comunes, útiles y poco técnicas como para que hayamos decidido 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, o no usarse, en las descripciones de los ejercicios, pero no están restringidas en otros textos del sitio (p. ej., los textos del sitio web, la mentoría).

Muchas guías de estilo del inglés estadounidense indican que las abreviaturas «i.e.» y «e.g.» deben ir seguidas de una coma (ver, p. ej., este hilo de StackExchange). Esto está permitido, pero no es obligatorio en el texto de Exercism.

Elección de las palabras

Términos matemáticos y jerga

Siempre que se usen términos matemáticos, hay que explicarlos o sustituirlos por términos que requieran menos conocimiento del área.

Ejemplos:

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

Código

Todo el código debe tener un formato consistente que siga las convenciones de estilo de su track. Cuando sea posible, estas convenciones de todo el track deben coincidir con las convenciones de estilo preferidas del lenguaje.