Exercism stílusútmutatója

Ez a dokumentum stílusútmutatóként szolgál a feladatokban használt nyelvezethez és szövegezéshez.

Alkalmazás

Ezeket a szabályokat minden feladatban be kell tartani. A meglévő leírások és tesztesetek frissíthetők, hogy megfeleljenek nekik, anélkül hogy „csere” tesztesetekre lenne szükség.

Egységesség egy feladaton belül

Van néhány kifejezés, amelynek több érvényes írásmódja is létezik (pl. „lower case” vs. „lowercase”). Ahol ebben a dokumentumban nem született megállapodás az egységes írásmódról, ott ezeknek egy feladaton belül kell egységesnek lenniük.

Kivételek

A feladatok eltérhetnek ezektől a szabályoktól, ha a karbantartók körében általános egyetértés van abban, hogy ez ésszerű. Például egy különböző mértékegységek közötti átváltásról szóló feladat dönthet úgy, hogy nem használ SI-mértékegységeket.

Nyelvezet

Minden tartalmat amerikai angol nyelven kell írni, amely több szempontból különbözik a brit angoltól. A jövőben más fordítások is születhetnek, de az Exercism „hivatalos” nyelve az amerikai angol.

Mértékegységek

Minden mértékegységnek SI vagy SI-ből származtatott mértékegységnek kell lennie.

Rövidítések, mozaikszavak és betűszavak

A rövidítések, mozaikszavak és betűszavak gyakran nehezebben érthetők, mint más megfogalmazások, és elidegeníthetik a tanulni próbálókat.

Sok rövidítés szakzsargon. Ahol lehet, kerüld a szakzsargont más megfogalmazások használatával. Ne használj rövidítést, hacsak nem igaz az alábbiak egyike:

  • A rövidített kifejezést jobban ismerik, mint a rövidítés nélkülit
  • A szöveg a rövidítés nélkül túlzottan terjengős lenne

Amikor rövidítést használsz, mindig magyarázd el, mit jelent a kifejezés, amikor először előfordul. Ez gyakran, de nem mindig jelenti a rövidítés feloldását. Ritkán elegendő csupán feloldani a rövidítést.

Íme néhány példaszabály:

  • Inkább „if I recall correctly”, mint „IIRC”
  • Inkább „as far as I know”, mint „AFAIK”
  • Inkább „queue”, mint „FIFO”, és inkább „stack”, mint „FILO”
  • Ahelyett hogy egy interfészt „RESTful”-ként írnál le, írd le a konkrét tulajdonságait
  • Ha muszáj a „CRUD”-ot használnod, magyarázd el, hogy a Create, Read, Update, Delete rövidítése, és hogy ezek a szabványos adatbázisok alapvető műveletei

És néhány példa a helyes használatra:

  • „HyperText Markup Language (HTML) is the language used to describe document structure and content on the web” (feloldva és elmagyarázva)
  • „DNA, a set of chemical instructions that influence how our bodies are constructed” (a DNA nincs feloldva, mert a „deoxyribonucleic acid” valószínűleg nem segítene elmagyarázni, mi a DNA a közönségünknek)
  • „NASA, the United States' space agency, launched the Mariner 2 space probe in...” (a NASA nincs feloldva, mert a „National Aerospace and Space Administration”-t sokkal jobban ismerik a betűszava alapján, mint a feloldott neve alapján)
  • „The Department of Motor Vehicles (DMV) is filled with sloths. That's why everything takes forever at the DMV” (a DMV-t az első használatkor definiáld)

Nyelvtan

Az oxfordi vessző

A felsorolásokban használd az „oxfordi vesszőt” (más néven sorolóvesszőt). Például ahelyett, hogy „I love my parents, Lady Gaga and Humpty Dumpty”, írd azt, hogy „I love my parents, Lady Gaga, and Humpty Dumpty”. Lehet, hogy ezt a képet is szórakoztatónak találod magyarázatként.

Kivételek

Néhány rövidítést elég gyakorinak, hasznosnak és nem eléggé technikai jellegűnek tartunk ahhoz, hogy engedélyezzük őket:

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

A feladatok leírásaiban az összevonásokat (pl. „won't”, „I'm”, „that's”) csak elvétve, vagy egyáltalán ne használd, a webhely többi szövegében viszont (pl. weboldal-szövegek, mentorálás) nincs korlátozás.

Sok amerikai angol stílusútmutató szerint az „i.e.” és az „e.g.” rövidítést vesszőnek kell követnie (lásd például ezt a StackExchange-beszélgetést). Ez megengedett, de nem kötelező az Exercism szövegeiben.

Szóhasználat

Matematikai kifejezések és szakzsargon

Ahol matematikai kifejezéseket használsz, azokat el kell magyarázni, vagy olyan kifejezésekre kell cserélni, amelyekhez kevesebb szakterületi tudás kell.

Példák:

  • A „natural numbers” helyett használjuk a „positive whole numbers” kifejezést.
  • Ha a „rational numbers” kifejezést akarjuk használni, azt a feladat bevezetőjében el kell magyarázni.
  • A range szó használata helyett (amelynek különböző kontextusokban más-más jelentése lehet) használd a „x < ? < y (greater than x and less than y)” formát.
  • Az „esoteric terms” helyett használd a „terms not understood by the majority of people” kifejezést.

Kód

Minden kódot a saját kurzusa stíluskonvencióinak megfelelően, egységesen kell formázni. Ahol lehet, ezeknek a kurzusszintű konvencióknak egyezniük kell a nyelv ajánlott stíluskonvencióival.