mirror of
https://github.com/godotengine/godot-docs-l10n.git
synced 2025-12-31 09:49:22 +03:00
315 lines
16 KiB
Plaintext
315 lines
16 KiB
Plaintext
# SOME DESCRIPTIVE TITLE.
|
|
# Copyright (C) 2014-present Juan Linietsky, Ariel Manzur and the Godot community (CC BY 3.0)
|
|
# This file is distributed under the same license as the Godot Engine package.
|
|
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
|
|
#
|
|
#, fuzzy
|
|
msgid ""
|
|
msgstr ""
|
|
"Project-Id-Version: Godot Engine 4.3\n"
|
|
"Report-Msgid-Bugs-To: \n"
|
|
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
|
|
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
|
|
"Language-Team: LANGUAGE <LL@li.org>\n"
|
|
"MIME-Version: 1.0\n"
|
|
"Content-Type: text/plain; charset=UTF-8\n"
|
|
"Content-Transfer-Encoding: 8bit\n"
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:4
|
|
msgid "Code style guidelines"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:8
|
|
msgid "When contributing to Godot's source code, you will be expected to follow the style guidelines outlined below. Some of them are checked via the Continuous Integration process and reviewers will ask you to fix potential issues, so best setup your system as outlined below to ensure all your commits follow the guidelines."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:15
|
|
msgid "C++ and Objective-C"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:17
|
|
msgid "There are no written guidelines, but the code style agreed upon by the developers is enforced via the `clang-format <https://clang.llvm.org/docs/ClangFormat.html>`__ code beautifier, which takes care for you of all our conventions. To name a few:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:22
|
|
msgid "Indentation and alignment are both tab based (respectively one and two tabs)"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:23
|
|
msgid "One space around math and assignments operators as well as after commas"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:24
|
|
msgid "Pointer and reference operators are affixed to the variable identifier, not to the type name"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:26
|
|
msgid "See further down regarding header includes"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:28
|
|
msgid "The rules used by clang-format are outlined in the `.clang-format <https://github.com/godotengine/godot/blob/master/.clang-format>`__ file of the Godot repository."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:32
|
|
msgid "As long as you ensure that your style matches the surrounding code and that you're not introducing trailing whitespace or space-based indentation, you should be fine. If you plan to contribute regularly, however, we strongly advise that you set up clang-format locally to check and automatically fix all your commits."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:37
|
|
msgid "Godot's code style should *not* be applied to third-party code, i.e. that is included in Godot's source tree but was not written specifically for our project. Such code usually comes from different upstream projects with their own style guides (or lack thereof), and don't want to introduce differences that would make syncing with upstream repositories harder."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:44
|
|
msgid "Third-party code is usually included in the ``thirdparty/`` folder and can thus easily be excluded from formatting scripts. For the rare cases where a third-party code snippet needs to be included directly within a Godot file, you can use ``/* clang-format off */`` and ``/* clang-format on */`` to tell clang-format to ignore a chunk of code."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:53
|
|
msgid "These guidelines only cover code formatting. See :ref:`doc_cpp_usage_guidelines` for a list of language features that are permitted in pull requests."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:58
|
|
msgid "Using clang-format locally"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:60
|
|
msgid "You need to use **clang-format 17** to be compatible with Godot's format. Later versions might be suitable, but previous versions may not support all used options, or format some things differently, leading to style issues in pull requests."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:67
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:308
|
|
msgid "Pre-commit hook"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:69
|
|
msgid "For ease of use, we provide hooks for Git with the `pre-commit <https://pre-commit.com/>`__ Python framework that will run clang-format automatically on all your commits with the correct version of clang-format. To set up:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:80
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:321
|
|
msgid "You can also run the hook manually with ``pre-commit run``."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:84
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:325
|
|
msgid "Previously, we supplied a hook in the folder ``misc/hooks``. If you copied the script manually, these hooks should still work, but symlinks will be broken. If you are using the new system, run ``rm .git/hooks/*`` to remove the old hooks that are no longer needed."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:91
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:280
|
|
msgid "Installation"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:93
|
|
msgid "Here's how to install clang-format:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:95
|
|
msgid "Linux: It will usually be available out-of-the-box with the clang toolchain packaged by your distribution. If your distro version is not the required one, you can download a pre-compiled version from the `LLVM website <https://releases.llvm.org/download.html>`__, or if you are on a Debian derivative, use the `upstream repos <https://apt.llvm.org/>`__."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:100
|
|
msgid "macOS and Windows: You can download precompiled binaries from the `LLVM website <https://releases.llvm.org/download.html>`__. You may need to add the path to the binary's folder to your system's ``PATH`` environment variable to be able to call clang-format out of the box."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:105
|
|
msgid "You then have different possibilities to apply clang-format to your changes:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:108
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:292
|
|
msgid "Manual usage"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:110
|
|
msgid "You can apply clang-format manually for one or more files with the following command:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:117
|
|
msgid "``-i`` means that the changes should be written directly to the file (by default clang-format would only output the fixed version to the terminal)."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:119
|
|
msgid "The path can point to several files, either one after the other or using wildcards like in a typical Unix shell. Be careful when globbing so that you don't run clang-format on compiled objects (.o and .a files) that are in Godot's tree. So better use ``core/*.{cpp,h}`` than ``core/*``."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:126
|
|
msgid "IDE plugin"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:128
|
|
msgid "Most IDEs or code editors have beautifier plugins that can be configured to run clang-format automatically, for example, each time you save a file."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:131
|
|
msgid "Here is a non-exhaustive list of beautifier plugins for some IDEs:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:133
|
|
msgid "Qt Creator: `Beautifier plugin <https://doc.qt.io/qtcreator/creator-beautifier.html>`__"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:134
|
|
msgid "Visual Studio Code: `Clang-Format <https://marketplace.visualstudio.com/items?itemName=xaver.clang-format>`__"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:135
|
|
msgid "Visual Studio: `Clang Power Tools 2022 <https://marketplace.visualstudio.com/items?itemName=caphyon.ClangPowerTools2022>`__"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:136
|
|
msgid "vim: `vim-clang-format <https://github.com/rhysd/vim-clang-format>`__"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:137
|
|
msgid "CLion: Starting from version ``2019.1``, no plugin is required. Instead, enable `ClangFormat <https://www.jetbrains.com/help/clion/clangformat-as-alternative-formatter.html#clion-support>`__"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:140
|
|
msgid "(Pull requests are welcome to extend this list with tested plugins.)"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:145
|
|
msgid "Header includes"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:147
|
|
msgid "When adding new C++ or Objective-C files or including new headers in existing ones, the following rules should be followed:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:150
|
|
msgid "The first lines in the file should be Godot's copyright header and MIT license, copy-pasted from another file. Make sure to adjust the filename."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:152
|
|
msgid "In a ``.h`` header, include guards should be used with the form ``FILENAME_H``."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:155
|
|
msgid "In a ``.cpp`` file (e.g. ``filename.cpp``), the first include should be the one where the class is declared (e.g. ``#include \"filename.h\"``), followed by an empty line for separation."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:158
|
|
msgid "Then come headers from Godot's own code base, included in alphabetical order (enforced by ``clang-format``) with paths relative to the root folder. Those includes should be done with quotes, e.g. ``#include \"core/object.h\"``. The block of Godot header includes should then be followed by an empty line for separation."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:163
|
|
msgid "Finally, third-party headers (either from ``thirdparty`` or from the system's include paths) come next and should be included with the < and > symbols, e.g. ``#include <png.h>``. The block of third-party headers should also be followed by an empty line for separation."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:167
|
|
msgid "Godot and third-party headers should be included in the file that requires them, i.e. in the `.h` header if used in the declarative code or in the `.cpp` if used only in the imperative code."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:171
|
|
msgid "Example:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:259
|
|
msgid "Java"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:261
|
|
msgid "Godot's Java code (mostly in ``platform/android``) is also enforced via ``clang-format``, so see the instructions above to set it up. Keep in mind that this style guide only applies to code written and maintained by Godot, not third-party code such as the ``java/src/com/google`` subfolder."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:267
|
|
msgid "Python"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:269
|
|
msgid "Godot's SCons buildsystem is written in Python, and various scripts included in the source tree are also using Python."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:272
|
|
msgid "For those, we use the `Ruff linter and code formatter <https://docs.astral.sh/ruff/>`__."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:275
|
|
msgid "Using ruff locally"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:277
|
|
msgid "First of all, you will need to install Ruff. Ruff requires Python 3.7+ to run."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:282
|
|
msgid "Here's how to install ruff:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:289
|
|
msgid "You then have different possibilities to apply ruff to your changes:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:294
|
|
msgid "You can apply ``ruff`` manually to one or more files with the following command:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:301
|
|
msgid "``-l 120`` means that the allowed number of characters per line is 120. This number was agreed upon by the developers."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:303
|
|
msgid "The path can point to several files, either one after the other or using wildcards like in a typical Unix shell."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:310
|
|
msgid "For ease of use, we provide hooks for Git with the `pre-commit <https://pre-commit.com/>`__ Python framework that will run ``ruff`` automatically on all your commits with the correct version of ``ruff``. To set up:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:332
|
|
msgid "Editor integration"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:334
|
|
msgid "Many IDEs or code editors have beautifier plugins that can be configured to run ruff automatically, for example, each time you save a file. For details, you can check `Ruff Integrations <https://docs.astral.sh/ruff/integrations/>`__."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:339
|
|
msgid "Comment style guide"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:341
|
|
msgid "This comment style guide applies to all programming languages used within Godot's codebase."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:344
|
|
msgid "Begin comments with a space character to distinguish them from disabled code."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:345
|
|
msgid "Use sentence case for comments. Begin comments with an uppercase character and always end them with a period."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:347
|
|
msgid "Reference variable/function names and values using backticks."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:348
|
|
msgid "Wrap comments to ~100 characters."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:349
|
|
msgid "You can use ``TODO:``, ``FIXME:``, ``NOTE:``, or ``HACK:`` as admonitions when needed."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:352
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:375
|
|
msgid "**Example:**"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:360
|
|
msgid "Don't repeat what the code says in a comment. Explain the *why* rather than *how*."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:362
|
|
msgid "**Bad:**"
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:369
|
|
msgid "You can use Javadoc-style comments above function or macro definitions. It's recommended to use Javadoc-style comments *only* for methods which are not exposed to scripting. This is because exposed methods should be documented in the :ref:`class reference XML <doc_updating_the_class_reference>` instead."
|
|
msgstr ""
|
|
|
|
#: ../../docs/contributing/development/code_style_guidelines.rst:387
|
|
msgid "For member variables, don't use Javadoc-style comments but use single-line comments instead:"
|
|
msgstr ""
|