Guida di stile di Exercism

Questo documento funge da guida di stile per la lingua e la formulazione usate negli esercizi.

Applicazione

Queste regole vanno seguite in tutti gli esercizi. Le descrizioni e i casi di test esistenti possono essere aggiornati per adeguarvisi, senza bisogno di casi di test «sostitutivi».

Coerenza all'interno di un esercizio

Alcuni termini hanno più grafie valide (es. «lower case» e «lowercase»). Quando questo documento non fissa uno stile coerente per un termine, la coerenza va comunque garantita all'interno del singolo esercizio.

Eccezioni

Gli esercizi possono discostarsi da queste regole se tra i maintainer c'è un consenso generale sul fatto che sia ragionevole. Per esempio, un esercizio sulla conversione tra unità diverse potrebbe scegliere di non usare le misure SI.

Lingua

Tutti i contenuti vanno scritti in inglese americano, che differisce dall'inglese britannico in svariati modi. In futuro potranno esserci altre traduzioni, ma la lingua «ufficiale» di Exercism è l'inglese americano.

Misure

Tutte le unità di misura devono essere unità SI o derivate dal SI.

Abbreviazioni, acronimi e sigle

Le abbreviazioni, gli acronimi e le sigle sono spesso più difficili da capire rispetto ad altre formulazioni e possono allontanare chi sta cercando di imparare.

Molte abbreviazioni sono gergo. Evita il gergo dove possibile, usando un linguaggio alternativo. Non usare le abbreviazioni a meno che non valga almeno una di queste condizioni:

  • Il termine abbreviato è più conosciuto del termine per esteso
  • Il testo diventerebbe eccessivamente prolisso senza l'abbreviazione

Quando usi un'abbreviazione, spiega sempre cosa significa il termine alla sua prima occorrenza. Spesso, ma non sempre, questo comprende lo scioglimento dell'abbreviazione. Raramente basta limitarsi a scioglierla.

Ecco alcune regole di esempio:

  • Preferisci «if I recall correctly» a «IIRC»
  • Preferisci «as far as I know» a «AFAIK»
  • Preferisci «queue» a «FIFO» e «stack» a «FILO»
  • Invece di descrivere un'interfaccia come «RESTful», descrivine le proprietà specifiche
  • Se devi proprio usare «CRUD», spiega che sta per Create, Read, Update, Delete e che queste sono le azioni di base nei database standard

Ed ecco alcuni esempi di buon uso:

  • «HyperText Markup Language (HTML) is the language used to describe document structure and content on the web» (sciolto e spiegato)
  • «DNA, a set of chemical instructions that influence how our bodies are constructed» (DNA non viene sciolto perché «deoxyribonucleic acid» difficilmente aiuterebbe il nostro pubblico a capire cos'è il DNA)
  • «NASA, the United States' space agency, launched the Mariner 2 space probe in...» (NASA non viene sciolto perché «National Aerospace and Space Administration» è molto più conosciuto con il suo acronimo che con il nome per esteso)
  • «The Department of Motor Vehicles (DMV) is filled with sloths. That's why everything takes forever at the DMV» (definisci DMV la prima volta che lo usi)

Grammatica

Virgola di Oxford

Usa la Oxford Comma (nota anche come «Serial Comma») negli elenchi. Per esempio, invece di «I love my parents, Lady Gaga and Humpty Dumpty», scrivi «I love my parents, Lady Gaga, and Humpty Dumpty». Potresti anche apprezzare questa immagine come spiegazione.

Eccezioni

Alcune abbreviazioni sono considerate abbastanza comuni, utili e non tecniche da farci decidere di permetterle:

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

Le contrazioni (es. «won't», «I'm», «that's») vanno usate con parsimonia, se non addirittura evitate, nelle descrizioni degli esercizi, ma non sono vietate negli altri testi del sito (es. i testi delle pagine web, il mentoring).

Molte guide di stile dell'inglese americano affermano che le abbreviazioni «i.e.» e «e.g.» dovrebbero essere seguite da una virgola (vedi, per esempio, questo thread su StackExchange). Nei testi di Exercism questo è permesso, ma non obbligatorio.

Scelta delle parole

Termini matematici e gergali

Ogni volta che si usano termini matematici, questi vanno spiegati o sostituiti con termini che richiedono meno conoscenze specifiche.

Esempi:

  • Invece di «natural numbers», dovremmo usare «positive whole numbers».
  • Se vogliamo usare l'espressione «rational numbers», dobbiamo spiegarla nell'introduzione dell'esercizio.
  • Invece di usare la parola «range» (che può avere significati diversi in contesti diversi), usa «x < ? < y (greater than x and less than y)».
  • Invece di «esoteric terms», usa l'espressione «terms not understood by the majority of people».

Codice

Tutto il codice dovrebbe essere formattato in modo coerente seguendo le convenzioni di stile della sua traccia. Quando è possibile, queste convenzioni valide per l'intera traccia dovrebbero corrispondere alle convenzioni di stile preferite dal linguaggio.