Користувач:Роман Рябенко/Зрозумілість модулів
Перейти до навігації
Перейти до пошуку
Це — особиста чернетка користувача Роман Рябенко. |
Як підвищити зрозумілість коду модулів Lua для більшого кола дописувачів?
- Називати одним і тим самим словом те, що позначає одне й те саме: наприклад, функцію, яка реалізує функціонал шаблону, слід назвати так само, як шаблон. Відповідно, не слід використовувати однакове позначення для різних елементів, наприклад просто «x» або «zminna» на позначення змінної в різних функціях, які обробляють різні дані.
- Використовувати транслітерацію для назв змінних і функцій. Це полегшує реалізацію пункту вище, а також наступний пункт.
- Компонувати код, щоб те, що він робить, вгадувалося, як з написаного прозою. Давати описові назви змінним і функціям. Використовувати повні слова для назв змінних і функцій. Використовувати знак підкреслення «_» для розділення слів у назві зміїним регістром, замість верблюдячого регістру
- Розміщувати код у послідовності, яка відповідає послідовності виводу та послідовності обробки параметрів.
- Супроводжувати код коментарями, які пояснюють, що він робить. Пояснювати в коментарях кожен крок, в тому числі «очевидний» код і код, який присутній в будь-якому модулі. Не робити припущень, що читач коду розуміється на програмуванні чи Lua. Писати коментарі до коду українською мовою.
- Переносити задовгі рядки коду, структуруючи його вертикально. Дотримуватися табульованих відступів.
- На початку модуля описати його зміст і структуру в коментарі.
- В документації до модуля зазначити, які завдання він вирішує.
У разі запозичення коду з англомовної Вікіпедії, запозичення зручніше оновлювати, якщо правил вище не дотримуватися. Але англомовна Вікіпедія йде своїм шляхом, а модулі в україномовній Вікіпедії в результаті залишаються застарілими, бо мало хто розуміє, як вони працюють. Навіть якщо користувач не може самостійно внести зміни, йому буде простіше знайти частину коду, щодо якої подати запит.