Інструкції з написання

Спільнота Godot є багатою та міжнародною. Користувачі приходять з усього світу. Деякі з них молоді, а багатьом англійська не є рідною. Тому всі ми повинні писати зрозумілою та спільною мовою. Для довідкового матеріалу класу мета полягає в тому, щоб зробити його легким для читання всім і точним.

Таким чином, завжди намагайтеся:

Використовуйте активний голос
Використовуйте точні дієслова для опису дій
Уникайте дієслів, які завершуються на -ing
Вилучайте непотрібні прикметники і прислівники.
Забороніть ці 8 слів: очевидний, простий, основний, легкий, актуальний, справедливий, зрозумілий і все ж
Використовуйте явні посилання
Використовуйте 's, щоб показати належність
Використовуйте оксфордську кому

Є 3 правила для опису класів:

У короткому описі дайте огляд вузла
Згадайте, які методи повертають, якщо це корисно
Використовуйте «якщо істина» для опису логічних значень

Примітка

Завдання технічного автора полягає в тому, щоб упакувати якомога більше інформації в найкоротші та найчіткіші речення. Ці рекомендації допоможуть вам досягти цієї мети.

Дивись також

Перегляньте content guidelines, щоб дізнатися про типи документів, які ви можете писати в офіційній документації.

7 правил чіткої англійської

Використовуйте активний голос

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

Пасивний спосіб:

The man **was bitten** by the dog.

Активний спосіб:

The dog bit the man.

Не використовуйте пасивний спосіб:

void edit_set_pivot ( Vector2 pivot )
[...] This method **is implemented** only in some nodes that inherit Node2D.

Використовуйте назву вузла як іменник:

void edit_set_pivot ( Vector2 pivot )
[...] Only some Node2Ds **implement** this method.

Використовуйте точні дієслова для опису дій

Віддавайте перевагу точним, але загальним дієсловам, а не загальним, таким як «зробити», «встановити» та будь-якому виразу, який можна замінити одним словом.

Не повторюйте назву методу. Він уже вказує, що встановлює нове значення опорного значення:

void edit_set_pivot ( Vector2 pivot )
Set the pivot position of the 2D node to [code]pivot[/code] value. [...]

Поясніть, що є наслідком цього «набору»: використовуйте точні дієслова, як-от place, position, rotate, fade тощо.

void edit_set_pivot ( Vector2 pivot )
Position the node's pivot to the [code]pivot[/code] value. [...]

Уникайте дієслів, які завершуються на -ing

Прогресивні форми описують безперервні дії. наприклад «кличе», «рухається».

Не використовуйте прогресивну форму для миттєвих змін.

Vector2 move ( Vector2 rel_vec )
Move the body in the given direction, **stopping** if there is an obstacle. [...]

Використовуйте простий теперішній, минулий або майбутній час.

Vector2 move ( Vector2 rel_vec )
Moves the body in the vector's direction. The body **stops** if it collides with an obstacle. [...]

Виняток: якщо тема незрозуміла, заміна дієслів "ing" не є покращенням. Наприклад, у попередньому реченні «це замінює» не мало б особливого сенсу там, де зараз є «замінити».

Ви можете використовувати прогресивний час, щоб описати дії, які тривають у часі. Щось на зразок анімації чи співпрограм.

Порада

Дієслова можуть перетворюватися на іменники-прикметники за допомогою -ing. Це не сполучення, тому ви можете використовувати їх: залишок руху, відсутній файл тощо.

Вилучіть непотрібні прислівники та прикметники

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

Не використовуйте зайві або безглузді прислівники. Слова, які подовжують документацію, але не додають жодної інформації:

**Basically** a big texture [...]

Пишіть короткі речення простою, описовою мовою:

A big texture [...]

Не використовуйте ці 8 слів

Ніколи не використовуйте ці 8 заборонених слів:

очевидно (obvious)
просто (simple)
базовий (basic)
простий (easy)
насправді (actual)
лише (just)
clear
втім (however, деякі з використань)

Створення ігор і програмування не є простими, і немає нічого легкого для тих, хто вчиться використовувати API вперше. Інші слова зі списку, як-от просто або фактично, не додадуть жодної інформації до речення. Не вживайте також відповідних прислівників: очевидно, просто, в основному, легко, власне, зрозуміло.

Приклад Не. Заборонені слова подовжують опис і відволікають увагу від найважливішої інформації:

**TextureRect**
Control frame that **simply** draws an assigned texture. It can stretch or not. It's a **simple** way to **just** show an image in a UI.

Видаліть їх:

**TextureRect**
[Control] node that displays a texture. The texture can stretch to the node's bounding box or stay in the center. Useful to display sprites in your UIs.

«Просте» ніколи не допомагає. Пам’ятайте, що для інших користувачів усе може бути складним або розчарувати. Немає нічого кращого старого доброго це просто, щоб змусити вас здригнутися. Ось старий короткий опис, перше речення на сторінці вузла Timer:

**Timer**
A **simple** Timer node.

Поясніть, що робить вузол замість цього:

**Timer**
Calls a function of your choice after a certain duration.

Не використовуйте «основний», він надто розпливчастий:

**Vector3**
Vector class, which performs **basic** 3D vector math operations.

Використовуйте короткий опис, щоб запропонувати огляд вузла:

**Vector3**
Provides essential math functions to manipulate 3D vectors: cross product, normalize, rotate, etc.

Використовуйте явні посилання

Віддавайте перевагу явним посиланням над неявними.

Не використовуйте такі слова, як «перший», «останній» тощо. Вони не є найпоширенішими в англійській мові, тому вам потрібно перевірити посилання.

[code]w[/code] and [code]h[/code] define right and bottom margins. The **latter** two resize the texture so it fits in the defined margin.

Повторюйте слова. Вони знімають усю двозначність:

[code]w[/code] and [code]h[/code] define right and bottom margins. **[code]w[/code] and [code]h[/code]** resize the texture so it fits the margin.

Якщо вам потрібно повторити одне й те саме ім’я змінної 3 або 4 рази, можливо, вам доведеться перефразувати свій опис.

Використовуйте 's, щоб показати належність

Уникайте «коров’ячого молока». Англійською це виглядає неприродно. Замість цього напишіть «Коров’яче молоко».

Не пишіть «X»:

The region **of the AtlasTexture that is** used.

Використовуйте 's. Це дозволяє поставити головну тему на початку речення та зробити його коротким:

The **AtlasTexture's** used region.

Використовуйте оксфордську кому, щоб перерахувати будь-що

З оксфордського словника:

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

[...] Не всі автори та видавці використовують його, але він може прояснити значення речення, коли елементи в списку не є окремими словами: Ці елементи доступні в чорному та білому, червоному та жовтому, синьому та зелений.

Не залишайте останній елемент списку без коми:

Create a CharacterBody2D node, a CollisionShape2D node and a sprite node.

Додайте кому перед «і» або «або» для останнього елемента списку з більш ніж двома елементами.

Create a CharacterBody2D node, a CollisionShape2D node, and a sprite node.

Як писати методи та класи

Динамічне проти статичної типізації

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

Виняток становлять теми, які пояснюють користувачам концепції статичного набору тексту.

Не додавайте підказку типу з двокрапкою або шляхом приведення:

const MainAttack := preload("res://fire_attack.gd")
var hit_points := 5
var name: String = "Bob"
var body_sprite := $Sprite2D as Sprite2D

Робіть запис констант і змінних за допомогою динамічної типізації:

const MainAttack = preload("res://fire_attack.gd")
var hit_points = 5
var name = "Bob"
var body_sprite = $Sprite2D

Не пишіть функції з виведеними аргументами або типами повернення:

func choose(arguments: PackedStringArray) -> String:
    # Chooses one of the arguments from array with equal chances
    randomize()
    var size := arguments.size()
    var choice: int = randi() % size
    return arguments[choice]

Пишіть функції за допомогою динамічного введення:

func choose(arguments):
    # Chooses one of the arguments from array with equal chances
    randomize()
    var size = arguments.size()
    var choice = randi() % size
    return arguments[choice]

Використовуйте реальні приклади коду, де це доречно

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

Написання var speed = 10 замість var my_var = 10 дозволяє новачкам краще зрозуміти код. Це дає їм орієнтир щодо того, де вони можуть використовувати фрагменти коду в реальному проекті.

Не пишіть вигадані приклади:

@onready var a = preload("res://MyPath")
@onready var my_node = $MyNode


func foo():
    # Do stuff

Напишіть конкретні приклади:

@onready var sfx_player_gun = preload("res://Assets/Sound/SFXPlayerGun.ogg")
@onready var audio_player = $Audio/AudioStreamPlayer


func play_shooting_sound():
    audio_player.stream = sfx_player_gun
    audio_player.play()

Звичайно, бувають випадки, коли використання реальних прикладів є недоцільним. У таких ситуаціях вам слід уникати використання таких імен, як my_var, foo() або my_func() і розглянути більш значущі імена для своїх прикладів.

У короткому описі дайте огляд вузла

Короткий опис є найважливішим реченням посилання. Це перший контакт користувача з вузлом:

Це єдиний опис у діалоговому вікні «Створити новий вузол».
Це у верхній частині кожної сторінки довідника

Короткий опис повинен пояснювати роль вузла та його функціональність (до 200 символів).

Не пишіть крихітні та розпливчасті резюме:

**Node2D**
Base node for 2D system.

Обов’язково надайте огляд функціональності вузла:

**Node2D**
A 2D game object, inherited by all 2D-related nodes. Has a position, rotation, scale, and Z index.

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

Згадайте, які методи повертають, якщо це корисно

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

Не використовуйте пасивний спосіб:

Vector2 move ( Vector2 rel_vec )
[...] The returned vector is how much movement was remaining before being stopped.

Завжди використовуйте «Повернення».

Vector2 move ( Vector2 rel_vec )
[...] Returns the remaining movement before the body was stopped.

Зверніть увагу на виняток із правила «прямого голосу»: за допомогою методу move зовнішній колайдер може впливати на метод і тіло, які викликають move. У цьому випадку можна використовувати пасивний стан.

Використовуйте «якщо істина» для опису логічних значень

Для логічних змінних-членів завжди використовуйте if true та/або if false, щоб залишатися явним. Контролює те, чи ні може бути неоднозначним і не працюватиме для кожної змінної-члена.

Крім того, оточіть логічні значення, назви змінних і методи [code][/code].

Починайте з «якщо правда»:

Timer.autostart
If [code]true[/code], the timer will automatically start when entering the scene tree.

Використовуйте `[код]` навколо аргументів

У посиланні на клас завжди оточуйте аргументи [code][/code]. У документації та в Godot він відображатиметься як це. Коли ви редагуєте XML-файли в репозиторії Godot, замініть існуючі аргументи, написані як 'this' або `this` на [code]this[/code].

Загальний словниковий запас для використання в документації Godot

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

У верхньому лівому кутку редактора знаходяться головні меню. У центрі кнопки змінюють робочу область. А разом кнопки у верхньому правому куті є кнопками відтворення. Область у центрі, яка відображає 2D або 3D простір, є окном перегляду. У верхній частині ви знайдете список інструментів всередині панелі інструментів.

Вкладки або закріплювані панелі по обидві сторони вікна перегляду є закріпленими. У вас є FileSystem dock, Scene dock, який містить ваше дерево сцени, Import dock, Node dock та Inspector або Inspector док. За допомогою макета за замовчуванням ви можете називати доки з вкладками вкладками: вкладка сцени, вкладка вузла...

Анімація, Налагоджувач тощо внизу вікна перегляду є панелями. Разом вони складають нижні панелі.

Області згортання Інспектора є розділами. Імена батьківських класів вузла, які ви не можете згорнути, є Класи, наприклад. клас CharacterBody2D. А окремі рядки з парами ключ-значення є властивості. наприклад position або modulate color є обидва властивості.

Вказівки щодо комбінацій клавіш

Комбінації клавіш і миші повинні використовувати :kbd: tag, which allows shortcuts to stand out from the rest of the text and inline code. Use the compact form for modifier keys (Ctrl/Cmd) замість їхньої прописаної форми (Control/Command). Для комбінацій використовуйте символ + з пробілом з обох боків від символу.

Обов’язково вкажіть ярлики, які відрізняються в macOS від інших платформ. Ви можете знайти список усіх ярликів, у тому числі те, що вони представляють у macOS, на this page.

Спробуйте якомога краще інтегрувати ярлик у речення. Ось кілька прикладів із тегом :kbd:, залишеним як є для кращої видимості:

Натисніть :kbd:`Ctrl + Alt + T`, щоб перемкнути панель (:kbd:`Opt + Cmd + T` на macOS).
Натисніть :kbd:`Space` і утримуйте ліву кнопку миші, щоб панорамувати у 2D-редакторі.
Натисніть :kbd:`Shift + Up Arrow`, щоб перемістити вузол вгору на 8 пікселів.

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

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

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

Примітка

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

Стилі тексту

Є кілька стилів, які використовуються в посібнику.

Стиль	Форматування RST	Типове використання
Відкритий текст	`text`	Використовується для більшості текстів.
Курсив	`text`	Використовується для наголосу. Використовується для введення нових термінів.
Жирний	`text`	Використовується для підкреслення та для інтерфейсу користувача редактора, наприклад меню та вікон.
`Code`	`` text ``	Використовується для назв змінних, літеральних значень і фрагментів коду. `code` використовується у багатьох випадках, коли ви використовуєте "цитований відкритий текст" типовою англійською мовою.
"Цитати"	`"text"`	Використовується для деяких літеральних значень або значень у лапках. У багатьох випадках перевага віддається іншому стилю.

Наголос

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

Надавайте перевагу використанню жирного шрифту для простого виділення.

Не закривайте вікно без попереднього збереження.

Використовуйте курсив або щоб підкреслити одне слово в контексті речення.

Ви можете додати вузол до сцени (але ви не можете підключити його).

Ви можете додати вузол до сцени (але ви не можете додати ресурс).

Ви можете додати вузол до сцени (але ви не можете додати його до ресурсу).

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

Godot використовує вузли зі сценаріями в дереві сцен.

Godot використовує вузли зі скриптами в дереві сцени.

Літерали

Використовуйте стиль коду для літеральних значень. Літерали включають:

Літерали типу Integer або int, наприклад 0, -2 або 100

Плаваючі літерали, як-от 0.0, 0.5, -2.0 або 100.0

Векторні літерали, наприклад (0.0, 0.0), (0.5, -0.5, 0.5) або (1.0, 2.0, 3.0, 4.0).

Класи, властивості та методи

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

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

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

Інтерфейс редактора

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

Відкрийте вікно Налаштування редактора.

Натисніть кнопку Підтвердити.

Змініть властивість вузла Transform > Position на (0, 0).

У вікні Налаштування проекту увімкніть перемикач Додаткові налаштування.

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

У Проект > Параметри проекту > Карта введення додайте нову дію введення.

Виберіть Сцена > Експортувати як... > MeshLibrary....

Виберіть Сцена > Експортувати як > MeshLibrary.

Примітка

Іноді як роздільник використовується -> або →. Це нестандартно. Замініть його на >, якщо ви вже вносите зміни в розділ.

Параметри проекту

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

Установіть параметр Application > Run > Max FPS на 60.

У налаштуваннях проекту в розділі Програма > Виконати встановіть Max FPS на 60.

У Налаштуваннях проекту > Програма > Виконати встановіть Max FPS на 60.

Ручне перенесення ліній

У підручнику рядки повинні бути перенесені вручну до не більше ніж 80-100 символів у рядку. Однак посилання не можна розбивати на кілька рядків і можуть перевищувати 100 символів. Таблиці також можуть перевищувати 100 символів.

Вносячи невеликі зміни, вам не потрібно вручну переносити весь абзац, якщо рядки не перевищують 100 символів.

Погано: Довжина рядка перевищує 100 символів:

The best thing to do is to wrap lines to under 80 characters per line. Wrapping to around 80-90 characters per line is also fine.
If your lines exceed 100 characters, you definitely need to add a newline! Don't forget to remove trailing whitespace when you do.

Добре: Рядки перенесені на 80-90 символів:

The best thing to do is to wrap lines to under 80 characters per line. Wrapping to
around 80-90 characters per line is also fine. If your lines exceed 100 characters, you
definitely need to add a newline! Don't forget to remove trailing whitespace when you do.

Найкраще: Рядки містять менше 80 символів:

The best thing to do is to wrap lines to under 80 characters per line. Wrapping
to around 80-90 characters per line is also fine. If your lines exceed 100
characters, you definitely need to add a newline! Don't forget to remove
trailing whitespace when you do.

Порада

У більшості текстових редакторів ви можете додати вертикальну напрямну або «лінійку» на 80 символів. Наприклад, у Visual Studio Code ви можете додати наступне до свого settings.json, щоб додати лінійки на 80 і 100 символів:

"editor.rulers": [80,100],

Синтаксис заголовка розділу

Використовуйте такий синтаксис для заголовків розділів:

Page title
==========

Renders as h1.
Every page has this.

Section header
--------------

Renders as h2.
Usually appears in sidebar. Many pages only need one level of nested headers.

Sub-section header
~~~~~~~~~~~~~~~~~~

Renders as h3.
Appears in sidebar in some pages, depending on how deeply nested the page is.

Sub-sub-section header
^^^^^^^^^^^^^^^^^^^^^^

Renders as h4.
Usually won't appear in the sidebar.

Наразі немає випадків глибшого вкладення заголовків, ніж цей. Уникайте будь-якого глибшого вкладення.

Зауважте, що заголовки не мають внутрішнього значення. У reStructuredText заголовки аналізуються на основі порядку, у якому вони спочатку з’являються на сторінці. Переконайтеся, що якщо ви використовуєте заголовок розділу h3 (~~~), ви спочатку включаєте заголовок підрозділу h2 (---).

Перегляньте документацію Sphinx та документацію reStructuredText для отримання додаткової інформації.

Коли посилатися на конкретну версію Godot

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

Дотримуйтесь цих вказівок, коли посилатися на певну версію Godot:

Якщо функцію було додано в поточну основну версію (4.x), ви можете вказати, що функція є новою в 4.x.
Якщо функція або підхід до проблеми за замовчуванням змінено між основними версіями (3.x -> 4.x), опишіть поточну функцію в основній частині сторінки та, за бажанням, додайте коротке речення або блок приміток для порівняння 3.x і 4.x.
Якщо велику функцію додано в проміжну версію 4.x, ви можете вказати проміжну версію під час її додавання. Великі функції мають цілу сторінку або великий розділ документації. У багатьох випадках цього все одно слід уникати, оскільки це актуально лише для кількох наступних проміжних версій.
Якщо невелику функцію додано в проміжну версію 4.x, не вказуйте проміжну версію під час її додавання. Невеликі функції мають лише короткий розділ документації або є незначними доповненнями до існуючих функцій.
Якщо стандартний підхід до проблеми змінено в проміжній версії 4.x, вкажіть проміжну версію, до якої було додано новий підхід за замовчуванням. Наприклад, зміна TileMap на TileMapLayer у 4.3.
Якщо функція була додана в основній або проміжній версії 3.x, не вказуйте, коли цю функцію було додано. Ці функції достатньо старі, тому точна версія, у якій вони були додані, не має значення.

Інструкції з написання

7 правил чіткої англійської

Використовуйте активний голос

Використовуйте точні дієслова для опису дій

Уникайте дієслів, які завершуються на -ing

Вилучіть непотрібні прислівники та прикметники

Не використовуйте ці 8 слів

Використовуйте явні посилання

Використовуйте 's, щоб показати належність

Використовуйте оксфордську кому, щоб перерахувати будь-що

Як писати методи та класи

Динамічне проти статичної типізації

Використовуйте реальні приклади коду, де це доречно

У короткому описі дайте огляд вузла

Згадайте, які методи повертають, якщо це корисно

Використовуйте «якщо істина» для опису логічних значень

Використовуйте [код] навколо аргументів

Загальний словниковий запас для використання в документації Godot

Вказівки щодо комбінацій клавіш

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

Стилі тексту

Наголос

Літерали

Класи, властивості та методи

Інтерфейс редактора

Параметри проекту

Ручне перенесення ліній

Синтаксис заголовка розділу

Коли посилатися на конкретну версію Godot

Використовуйте `[код]` навколо аргументів