Стиль кодування

У цьому розділі описано стиль вихідного коду, якому надає перевагу команда LinuxCNC.

1. Не нашкодь

Під час внесення невеликих змін до коду в стилі, відмінному від описаного нижче, враховуйте локальний стиль кодування. Швидкі зміни від одного стилю кодування до іншого знижують читабельність коду.

Ніколи не реєструйте код після виконання команди "indent". Зміни пробілів, внесені командою indent, ускладнюють відстеження історії редагувань файлу.

Не використовуйте редактор, який вносить непотрібні зміни до пробілів (наприклад, замінює 8 пробілів на табуляцію в рядку, який не змінено, або переносить слова в рядках, які не змінено).

2. Позиції табуляції

Позиція табуляції завжди відповідає 8 пробілам. Не пишіть код, який коректно відображається лише з іншим значенням позиції табуляції.

3. Відступ

Використовуйте 4 пробіли на рівень відступу. Об’єднання 8 пробілів в одну табуляцію прийнятне, але не обов’язкове.

4. Встановлення брекетів

Поставте відкриваючу фігурну дужку останньою на рядку, а закриваючу — першою:

if (x) {
    // зробити щось доречне
}

Закриваюча фігурна дужка стоїть на окремому рядку, за винятком випадків, коли за нею йде продовження того ж оператора, тобто while в операторі do або else в операторі if, як у цьому випадку:

do {
    // щось важливе
} while (x > 0);

if (x == y) {
    // зробити одну річ
} else if (x < y) {
    // зробити щось інше
} else {
    // зробити третю річ
}

Таке розміщення фігурних дужок також мінімізує кількість порожніх (або майже порожніх) рядків, що дозволяє одночасно відображати більшу кількість коду або коментарів у терміналі фіксованого розміру.

5. Ми

C є спартанською мовою, і так само має бути і ваша система іменування. На відміну від програмістів Modula-2 та Pascal, програмісти C не використовують милі імена на кшталт ThisVariableIsATemporaryCounter. Програміст C назвав би цю змінну «tmp», що набагато простіше писати і не менш зрозуміло.

Однак, описові назви для глобальних змінних є обов’язковими. Виклик глобальної функції «foo» — це кидок у ворота.

Глобальні змінні (які слід використовувати тільки в разі реальної необхідності) повинні мати описові імена, як і глобальні функції. Якщо у вас є функція, яка підраховує кількість активних користувачів, ви повинні назвати її «count_active_users()» або подібним чином, але не називати її «cntusr()».

Кодування типу функції в імені (так звана угорська нотація) є безглуздим — компілятор і так знає типи і може їх перевірити, а це тільки заплутує програміста. Не дивно, що Microsoft створює програми з помилками.

Імена локальних змінних повинні бути короткими і точними. Якщо у вас є випадковий цілочисельний лічильник циклу, його, ймовірно, слід назвати «i». Називати його «loop_counter» непродуктивно, якщо немає ймовірності його неправильного розуміння. Аналогічно, «tmp» може бути будь-яким типом змінної, яка використовується для зберігання тимчасового значення.

Якщо ви боїтеся переплутати назви локальних змінних, у вас є ще одна проблема, яка називається синдромом дисбалансу функції-гормону росту. Див. наступний розділ.

6. Функції

Функції повинні бути короткими, зрозумілими та виконувати лише одну дію. Вони повинні поміщатися на одному або двох екранах тексту (розмір екрана ISO/ANSI становить 80x24, як ми всі знаємо), виконувати одну дію та робити її добре.

Максимальна довжина функції обернено пропорційна складності та рівню втягування цієї функції. Отже, якщо у вас є концептуально проста функція, яка складається лише з одного довгого (але простого) оператора case, де вам доводиться виконувати багато дрібних операцій для багатьох різних випадків, то довша функція є цілком прийнятною.

Однак, якщо у вас є складна функція і ви підозрюєте, що не надто обдарований першокурсник середньої школи може навіть не зрозуміти, про що йдеться у цій функції, вам слід ще суворіше дотримуватися максимальних обмежень. Використовуйте допоміжні функції з описовими назвами (ви можете попросити компілятор вбудувати їх, якщо вважаєте, що це критично важливо для продуктивності, і він, ймовірно, зробить це краще, ніж ви).

Іншим показником функції є кількість локальних змінних. Їх не повинно бути більше 5-10, інакше ви робите щось не так. Перегляньте функцію і розділіть її на менші частини. Людський мозок зазвичай може легко відстежувати близько 7 різних речей, а якщо їх більше, він заплутується. Ви знаєте, що ви геніальний, але, можливо, ви хотіли б зрозуміти, що ви зробили через 2 тижні.

7. Коментування

Коментарі – це добре, але існує також небезпека надмірного коментування. НІКОЛИ не намагайтеся пояснити, ЯК працює ваш код у коментарі: набагато краще написати код так, щоб його робота була очевидною, а пояснювати погано написаний код – це марна трата часу.

Як правило, коментарі повинні пояснювати, ЩО робить ваш код, а не ЯК. Коментар у вигляді блоку, що описує функцію, значення, яке вона повертає, та хто її викликає, розміщений над тілом функції, є хорошим варіантом. Також намагайтеся уникати розміщення коментарів всередині тіла функції: якщо функція настільки складна, що вам потрібно окремо коментувати її частини, вам, ймовірно, слід перечитати розділ «Функції» ще раз. Ви можете робити невеликі коментарі, щоб зазначити або попередити про щось особливо розумне (або потворне), але намагайтеся уникати надмірності. Натомість розміщуйте коментарі на початку функції, розповідаючи людям, що вона робить, і, можливо, ЧОМУ вона це робить.

Якщо використовуються коментарі на кшталт /* Виправити мене */ , будь ласка, вкажіть, чому щось потрібно виправити. Після внесення змін до відповідної частини коду видаліть коментар або доповніть його, вказавши, що зміни внесено і їх потрібно протестувати.

8. Скрипти оболонки та Makefile

Не всі мають однакові інструменти та пакети. Деякі використовують vi, інші — emacs, а дехто взагалі уникає встановлення будь-якого з цих пакетів, віддаючи перевагу легким текстовим редакторам, таким як nano або вбудований у Midnight Commander.

gawk проти mawk - Знову ж таки, не у всіх буде встановлено gawk, mawk займає майже вдесятеро менше місця і при цьому відповідає стандарту POSIX AWK. Якщо знадобиться якась маловідома команда, специфічна для gawk, якої немає в mawk, то скрипт не працюватиме для деяких користувачів. Те саме стосується і mawk. Коротше кажучи, краще використовувати загальне виклик awk, а не gawk або mawk.

9. Умовні позначення C++

Стилі кодування C++ завжди можуть стати предметом гарячих суперечок (трохи як суперечки між прихильниками emacs і vi). Однак одне можна сказати напевно: єдиний стиль, який використовують усі учасники проекту, забезпечує однорідність і читабельність коду.

Правила іменування: Константи з #defines або переліків повинні бути написані великими літерами. Обґрунтування: Це полегшує виявлення констант часу компіляції в вихідному коді, наприклад, EMC_MESSAGE_TYPE.

Класи та простори імен повинні починатися з великої літери кожного слова та уникати символів підкреслення. Обґрунтування: Ідентифікує класи, конструктори та деструктори, наприклад, GtkWidget.

Методи (або назви функцій) повинні відповідати наведеним вище рекомендаціям щодо C та не повинні містити назви класу. Обґрунтування: Зберігає спільний стиль для вихідних кодів C та C++, наприклад, get_foo_bar().

Однак булеві методи легше читати, якщо в них не використовуються підкреслення і застосовується префікс «is» (не плутати з методами, що маніпулюють булевим значенням). Обґрунтування: ідентифікує значення, що повертається, як TRUE або FALSE і ніщо інше, наприклад, isOpen, isHomed.

НЕ використовуйте Not у логічних назвах, це призводить лише до плутанини під час виконання логічних перевірок, наприклад, isNotOnLimit або is_not_on_limit є ПОГАНИМИ.

У назвах змінних слід уникати використання великих літер та підкреслень, за винятком локальних або приватних імен. Слід максимально уникати використання глобальних змінних. Обґрунтування: роз’яснює, які змінні є змінними, а які — методами. Публічні: наприклад, axislimit Приватні: наприклад, maxvelocity_ .

9.1. Спеціальні правила іменування методів

Терміни get та set слід використовувати там, де доступ до атрибута здійснюється безпосередньо. Обґрунтування: Вказує на призначення функції або методу, наприклад, get_foo set_bar.

Для методів, що використовують логічні атрибути, перевага надається методам set та reset. Обґрунтування: Як і вище. Наприклад, set_amp_enable reset_amp_fault

Математично інтенсивні методи повинні використовувати префікс compute. Обґрунтування: Показує, що це вимагає інтенсивних обчислень і перевантажуватиме процесор. Наприклад, compute_PID

Скорочень в іменах слід уникати, де це можливо. Виняток становлять імена локальних змінних. Обґрунтування: чіткість коду. Наприклад, покажчик є кращим варіантом, ніж ptr, обчислення є кращим варіантом, ніж cmp, порівняння знову є кращим варіантом, ніж cmp.

Перелічення та інші константи можуть мати префікс із загальною назвою типу, наприклад, enum COLOR { COLOR_RED, COLOR_BLUE };.

Слід уникати надмірного використання макросів та визначень – перевага надається використанню простих методів або функцій. Обґрунтування: Покращує процес налагодження.

Включення файлів заголовків Файли заголовків повинні бути включені у верхній частині вихідного файлу, а не розкидані по всьому тексту. Вони повинні бути відсортовані та згруповані за їх ієрархічним положенням у системі, причому файли нижчого рівня повинні бути включені першими. Шляхи до файлів заголовків НІКОЛИ не повинні бути абсолютними — замість цього використовуйте прапор -I компілятора для розширення шляху пошуку. Обґрунтування: заголовки можуть бути розташовані не в одному і тому ж місці на всіх системах.

Вказівники та посилання повинні мати символ посилання поруч з іменем змінної, а не з іменем типу. Обґрунтування: Зменшує плутанину, наприклад, float *x або int &i.

Неявні перевірки на нуль не слід використовувати, окрім булевих змінних, наприклад, if (spindle_speed != 0) НЕ if (spindle_speed).

Тільки оператори керування циклом повинні бути включені до конструкції for(), наприклад, sum = 0; for (i=0; i<10; i++) { sum += value[i]; }
НЕ: for (i=0, sum=0; i<10; i++) sum += value[i];.

Так само слід уникати виконуваних операторів в умовних операторах, наприклад, if (fd = open(file_name)) погано.

Слід уникати складних умовних операторів - натомість вводьте тимчасові логічні змінні.

Дужки слід використовувати в математичних виразах часто – не покладайтеся на пріоритет операторів, коли додаткові дужки можуть щось уточнити.

Імена файлів: Джерела та заголовки C++ використовують розширення .cc та .hh. Використання .c та .h зарезервовано для простого C. Заголовки призначені для оголошень класів, методів та структур, а не для коду (якщо функції не оголошені вбудованими).

10. Стандарти кодування Python

Використовуйте стиль PEP 8 для коду Python.

11. Стандарти комп’ютерного кодування

У частині оголошення файлу .comp починайте кожне оголошення з першого стовпця. Вставляйте додаткові порожні рядки, якщо вони допомагають групувати пов’язані елементи.

У кодовій частині .comp-файлу дотримуйтесь звичайного стилю кодування на C.