Настанови щодо стилю програмного коду

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

C++ і Objective-C

Письмових вказівок немає, але стиль коду, узгоджений розробниками, забезпечується за допомогою інструмента clang-format, який піклується про вас усіх наших конвенцій. Щоб назвати декілька:

• Відступи та вирівнювання залежать від табуляції (відповідно одна та дві табуляції)

• Відступи та вирівнювання залежать від табуляції (відповідно одна та дві табуляції)

• Оператори покажчика та посилання прикріплюються до ідентифікатора змінної, а не до імені типу

• Дивіться нижче щодо включення заголовка

Правила, які використовує clang-format, викладені у файлі .clang-format репозиторію Godot.

Якщо ви гарантуєте, що ваш стиль відповідає навколишньому коду та що ви не вводите кінцеві пробіли чи відступи на основі пробілів, у вас все буде добре. Однак якщо ви плануєте регулярно робити внески, ми наполегливо рекомендуємо вам налаштувати формат clang локально, щоб перевіряти та автоматично виправляти всі ваші коміти.

Попередження

Стиль коду Godot не слід застосовувати до коду сторонніх розробників, тобто коду, який включено до дерева вихідних кодів Godot, але не був написаний спеціально для нашого проекту. Такий код зазвичай надходить з різних проектів вищестоящого напряму з власними посібниками зі стилю (або їх відсутністю), і ми не хочемо вводити відмінності, які ускладнюють синхронізацію з попередніми репозиторіями.

Код третьої сторони зазвичай міститься в папці thirdparty/ і тому його можна легко виключити зі сценаріїв форматування. У рідкісних випадках, коли фрагмент коду третьої сторони потрібно включити безпосередньо у файл Godot, ви можете використовувати /* clang-format off */ і /* clang-format on */, щоб скажіть clang-format ігнорувати частину коду.

Дивись також

Ці вказівки стосуються лише форматування коду. Перегляньте Правила використання C++ список мовних функцій, які дозволені в запитах на витягування.

Використання clang-format локально

Вам потрібно використовувати clang-format 17, щоб бути сумісним із форматом Godot. Пізніші версії можуть підійти, але попередні версії можуть не підтримувати всі використовувані параметри або відформатувати деякі речі по-іншому, що призведе до проблем зі стилем у запитах на отримання.

Хук попередньої фіксації

Для зручності використання ми надаємо хуки для Git із фреймворком pre-commit Python, який автоматично запускатиме clang-format для всіх ваших комітів із правильною версією clang- формат. Щоб налаштувати:

pip install pre-commit
pre-commit install

Ви також можете запустити хук вручну за допомогою pre-commit run.

Примітка

Раніше ми розміщували хук у папці misc/hooks. Якщо ви скопіювали сценарій вручну, ці хуки все одно повинні працювати, але символічні посилання будуть пошкоджені. Якщо ви використовуєте нову систему, запустіть rm .git/hooks/*, щоб видалити старі хуки, які більше не потрібні.

Встановлення

Ось як встановити clang-format:

• Linux: зазвичай він доступний із пакетом інструментів clang, який укомплектовано вашим дистрибутивом. Якщо ваша версія дистрибутива не є потрібною, ви можете завантажити попередньо скомпільовану версію з веб-сайту LLVM, або, якщо ви використовуєте похідну версію Debian, використовуйте репозиториї вище за течією.

• macOS і Windows: попередньо скомпільовані двійкові файли можна завантажити з веб-сайту LLVM. Можливо, вам знадобиться додати шлях до теки двійкового файлу до системної змінної середовища PATH, щоб мати можливість викликати clang-format із коробки.

Тоді у вас є різні можливості застосувати clang-format до ваших змін:

Використання вручну

Ви можете застосувати clang-format вручну для одного або кількох файлів за допомогою такої команди:

clang-format -i <path/to/file(s)>

• -i означає, що зміни мають бути записані безпосередньо у файл (за замовчуванням clang-format виводить на термінал лише фіксовану версію).

• Шлях може вказувати на кілька файлів, один за одним або за допомогою символів підстановки, як у типовій оболонці Unix. Будьте обережні під час глоббування, щоб не запустити clang-format на скомпільованих об’єктах (файлах .o та .a), які знаходяться в дереві Godot. Тому краще використовувати core/*.{cpp,h}, ніж core/*.

Додаток до IDE

Більшість IDE або редакторів коду мають плагіни beautifier, які можна налаштувати на автоматичний запуск clang-format, наприклад, кожного разу, коли ви зберігаєте файл.

Ось неповний список плагінів beautifier для деяких IDE:

• Qt Creator: Плагін Beautifier

• Код Visual Studio: Clang-Format

• Visual Studio: Clang Power tools 2022

• вім: vim-clang-format

• CLion: починаючи з версії 2019.1 плагін не потрібен. Натомість увімкніть ClangFormat

(Запити на витягування вітаються, щоб розширити цей список перевіреними плагінами.)

Заголовок містить

Додаючи нові файли C++ або Objective-C або включаючи нові заголовки в існуючі, слід дотримуватися таких правил:

• Перші рядки у файлі мають бути заголовком авторського права Godot та ліцензією MIT, скопійованою з іншого файлу. Переконайтеся, що змінено назву файлу.

• У заголовку .h захисні засоби включення слід використовувати у формі FILENAME_H.

• У файлі .cpp (наприклад, filename.cpp) перше включення має бути тим, у якому оголошено клас (наприклад #include "filename.h"), за яким іде порожній рядок для розділення.

• Потім йдуть заголовки з власної кодової бази Godot, включені в алфавітному порядку (забезпечується clang-format) із шляхами відносно кореневої папки. Ці включення слід робити за допомогою лапок, напр. #include "core/object.h". Після цього за блоком заголовка Godot має слідувати порожній рядок для розділення.

• Нарешті, сторонні заголовки (або від thirdparty, або від шляхів включення системи) йдуть наступними і повинні бути включені з символами < і >, наприклад. #include <png.h>. Блок сторонніх заголовків також повинен супроводжуватися порожнім рядком для розділення.

• Заголовки Godot і сторонніх розробників слід включити у файл, який їх потребує, тобто в заголовок .h, якщо він використовується в декларативному коді, або в .cpp, якщо він використовується лише в імперативному коді.

Приклад:

my_new_file.h

/**************************************************************************/
/*  my_new_file.h                                                         */
/**************************************************************************/
/*                         This file is part of:                          */
/*                             GODOT ENGINE                               */
/*                        https://godotengine.org                         */
/**************************************************************************/
/* Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md). */
/* Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur.                  */
/*                                                                        */
/* Permission is hereby granted, free of charge, to any person obtaining  */
/* a copy of this software and associated documentation files (the        */
/* "Software"), to deal in the Software without restriction, including    */
/* without limitation the rights to use, copy, modify, merge, publish,    */
/* distribute, sublicense, and/or sell copies of the Software, and to     */
/* permit persons to whom the Software is furnished to do so, subject to  */
/* the following conditions:                                              */
/*                                                                        */
/* The above copyright notice and this permission notice shall be         */
/* included in all copies or substantial portions of the Software.        */
/*                                                                        */
/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,        */
/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF     */
/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. */
/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY   */
/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,   */
/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE      */
/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                 */
/**************************************************************************/

#ifndef MY_NEW_FILE_H
#define MY_NEW_FILE_H

#include "core/hash_map.h"
#include "core/list.h"
#include "scene/gui/control.h"

#include <png.h>

...

#endif // MY_NEW_FILE_H

my_new_file.cpp

/**************************************************************************/
/*  my_new_file.cpp                                                       */
/**************************************************************************/
/*                         This file is part of:                          */
/*                             GODOT ENGINE                               */
/*                        https://godotengine.org                         */
/**************************************************************************/
/* Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md). */
/* Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur.                  */
/*                                                                        */
/* Permission is hereby granted, free of charge, to any person obtaining  */
/* a copy of this software and associated documentation files (the        */
/* "Software"), to deal in the Software without restriction, including    */
/* without limitation the rights to use, copy, modify, merge, publish,    */
/* distribute, sublicense, and/or sell copies of the Software, and to     */
/* permit persons to whom the Software is furnished to do so, subject to  */
/* the following conditions:                                              */
/*                                                                        */
/* The above copyright notice and this permission notice shall be         */
/* included in all copies or substantial portions of the Software.        */
/*                                                                        */
/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,        */
/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF     */
/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. */
/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY   */
/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,   */
/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE      */
/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                 */
/**************************************************************************/

#include "my_new_file.h"

#include "core/math/math_funcs.h"
#include "scene/gui/line_edit.h"

#include <zlib.h>
#include <zstd.h>

Java

Java-код Godot (здебільшого в platform/android) також застосовується через clang-format, тому див. інструкції вище, щоб налаштувати його. Майте на увазі, що цей посібник із стилю стосується лише коду, написаного та підтримуваного Godot, а не стороннього коду, такого як підпапка java/src/com/google.

Python

Система збірки Godot SCons написана мовою Python, і різні сценарії, включені в дерево вихідних кодів, також використовують Python.

Для цього ми використовуємо Ruff linter і форматування коду.

Використання йоржа локально

Перш за все, вам потрібно буде встановити Ruff. Для роботи Ruff потрібен Python 3.7+.

Встановлення

Ось як встановити ruff:

pip3 install ruff --user

Тоді ви матимете різні можливості застосувати до ваших змін зміни:

Використання вручну

Ви можете застосувати ruff вручну до одного або кількох файлів за допомогою такої команди:

ruff -l 120 <path/to/file(s)>

• -l 120 означає, що дозволена кількість символів у рядку становить 120. Цю кількість узгодили розробники.

• Шлях може вказувати на кілька файлів, один за одним або за допомогою символів підстановки, як у типовій оболонці Unix.

Хук попередньої фіксації

Для зручності використання ми надаємо хуки для Git із фреймворком pre-commit Python, який автоматично запускатиме ruff для всіх ваших комітів із правильною версією йорж. Щоб налаштувати:

pip install pre-commit
pre-commit install

Ви також можете запустити хук вручну за допомогою pre-commit run.

Примітка

Раніше ми розміщували хук у папці misc/hooks. Якщо ви скопіювали сценарій вручну, ці хуки все одно повинні працювати, але символічні посилання будуть пошкоджені. Якщо ви використовуєте нову систему, запустіть rm .git/hooks/*, щоб видалити старі хуки, які більше не потрібні.

Інтеграція редактора

Багато IDE або редактори коду мають плагіни beautifier, які можна налаштувати на автоматичний запуск ruff, наприклад, кожного разу, коли ви зберігаєте файл. Щоб дізнатися більше, ви можете перевірити інтеграції Ruff.

Керівництво по стилю коментарів

Цей посібник зі стилю коментарів стосується всіх мов програмування, які використовуються в кодовій базі Godot.

• Починайте коментарі з пробілу, щоб відрізнити їх від вимкненого коду.

• Використовуйте регістр для коментарів. Починайте коментарі з великої літери і завжди закінчуйте їх крапкою.

• Посилання на імена та значення змінних/функцій за допомогою зворотних позначок.

• Розмістіть коментарі приблизно до 100 символів.

• Ви можете використовувати TODO:, FIXME:, NOTE:, WARNING: або HACK: як попередження, коли це необхідно.

Приклад

// Compute the first 10,000 decimals of Pi.
// FIXME: Don't crash when computing the 1,337th decimal due to `increment`
//        being negative.

Не повторюйте те, що говорить код у коментарі. Поясніть чому, а не як.

Неправильно:

// Draw loading screen.
draw_load_screen();

Ви можете використовувати коментарі у стилі Javadoc над визначеннями функцій або макросів. Рекомендовано використовувати коментарі у стилі Javadoc тільки для методів, які не піддаються сценаріям. Це пояснюється тим, що відкриті методи мають бути задокументовані в class reference XML.

Приклад

/**
 * Returns the number of nodes in the universe.
 * This can potentially be a very large number, hence the 64-bit return type.
 */
uint64_t Universe::get_node_count() {
    // ...
}

Для змінних-членів не використовуйте коментарі у стилі Javadoc, натомість використовуйте однорядкові коментарі:

class Universe {
    // The cached number of nodes in the universe.
    // This value may not always be up-to-date with the current number of nodes
    // in the universe.
    uint64_t node_count_cached = 0;
};