Користувач:Роман Рябенко/Зрозумілість модулів

Як підвищити зрозумілість коду модулів Lua для більшого кола дописувачів?

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

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