Цей документ слугує настановою зі стилю для мови та формулювань, уживаних у вправах.
Застосування
Цих правил слід дотримуватися в усіх вправах.
Наявні описи та тестові випадки можна оновити відповідно до них, не вимагаючи «замінних» тестових випадків.
Послідовність у межах вправи
Є терміни, які мають кілька припустимих написань (напр. «lower case» проти «lowercase»).
Там, де в цьому документі не узгоджено єдиного стилю, вони мають бути послідовними в межах однієї вправи.
Винятки
Вправи можуть відступати від цих правил, якщо серед супровідників є загальний консенсус, що це виправдано.
Наприклад, вправа про переведення між різними одиницями може вирішити не використовувати одиниці SI.
Мова
Увесь вміст слід писати американською англійською (US English), яка відрізняється від британської (UK English) у багатьох аспектах. У майбутньому можливі інші переклади, але «офіційною» мовою Exercism залишається американська англійська.
Одиниці вимірювання
Усі одиниці вимірювання мають бути одиницями SI або похідними від SI.
Скорочення, акроніми та ініціалізми
Скорочення, акроніми та ініціалізми часто важче зрозуміти, ніж інші варіанти формулювання, і вони можуть відштовхнути людей, які вчаться.
Багато скорочень є жаргоном. Уникаймо жаргону, де це можливо, добираючи інші слова. Не використовуймо скорочень, окрім випадків, коли:
- Скорочена форма відоміша за повну
- Текст без скорочення буде надто багатослівним
Коли ми вживаємо скорочення, завжди пояснюймо, що означає термін, при першому його використанні. Це часто, але не завжди, передбачає розшифрування скорочення. Рідко буває достатньо лише розшифрувати скорочення.
Ось кілька прикладів правил:
- Надаваймо перевагу «if I recall correctly» над «IIRC»
- Надаваймо перевагу «as far as I know» над «AFAIK»
- Надаваймо перевагу «queue» над «FIFO» та «stack» над «FILO»
- Замість опису інтерфейсу як «RESTful» описуймо його конкретні властивості
- Якщо без «CRUD» не обійтися, пояснімо, що це означає Create, Read, Update, Delete і що це базові дії у стандартних базах даних
А ось кілька прикладів вдалого вживання:
- «HyperText Markup Language (HTML) is the language used to describe document structure and content on the web» (розшифровано й пояснено)
- «DNA, a set of chemical instructions that influence how our bodies are constructed» (DNA не розшифровують, бо „deoxyribonucleic acid“ навряд чи допоможе пояснити нашій аудиторії, що таке DNA)
- «NASA, the United States' space agency, launched the Mariner 2 space probe in...» (NASA не розшифровують, бо „National Aerospace and Space Administration“ значно відоміше за своїм акронімом, ніж за повною назвою)
- «The Department of Motor Vehicles (DMV) is filled with sloths. That's why everything takes forever at the DMV» (Пояснюймо DMV при першому його вживанні)
Граматика
Оксфордська кома
У списках використовуймо «оксфордську кому» (її також називають послідовною комою). Наприклад, замість «I love my parents, Lady Gaga and Humpty Dumpty» пишімо «I love my parents, Lady Gaga, and Humpty Dumpty». А ще може потішити це зображення як пояснення.
Винятки
Деякі скорочення вважаються достатньо поширеними, корисними й нетехнічними, тож ми вирішили дозволити їх:
-
e.g. або eg
-
i.e. або ie
-
etc. або etc
docs
Стягнені форми (напр. «won't», «I'm», «that's») слід уживати ощадливо, а то й зовсім не вживати в описах вправ, але вони не обмежені в інших текстах сайту (напр. у текстах сайту, наставництві).
Багато настанов зі стилю американської англійської зазначають, що після скорочень «i.e.» та «e.g.» має стояти кома (див., напр., цю гілку на StackExchange). Це дозволено, але не обовʼязково в текстах на Exercism.
Вибір слів
Математичні терміни та жаргон
Скрізь, де вживаються математичні терміни, їх слід пояснювати або замінювати термінами, які вимагають менших предметних знань.
Приклади:
- Замість «natural numbers» краще вживати «positive whole numbers».
- Якщо ми хочемо вжити словосполучення «rational numbers», його потрібно пояснити у вступі до вправи.
- Замість слова range (яке може мати різні значення в різних контекстах) уживаймо «x < ? < y (greater than x and less than y)».
- Замість «esoteric terms» уживаймо словосполучення «terms not understood by the majority of people».
Код
Увесь код має бути однаково відформатований за стильовими домовленостями відповідного треку. Де можливо, ці домовленості, спільні для всього треку, мають збігатися зі стильовими домовленостями, яким надає перевагу сама мова.
