2023-01-12 20:49:14 +01:00
|
|
|
|
2022-03-18 17:46:08 +01:00
|
|
|
|
|
|
|
C++ usage guidelines
|
|
|
|
====================
|
|
|
|
|
|
|
|
Rationale
|
|
|
|
---------
|
|
|
|
|
2024-03-16 20:56:52 +01:00
|
|
|
Since Pandemonium 4.0, the C++ standard used throughout the codebase is a subset of
|
2022-03-18 17:46:08 +01:00
|
|
|
**C++17**. While modern C++ brings a lot of opportunities to write faster, more
|
|
|
|
readable code, we chose to restrict our usage of C++ to a subset for a few
|
|
|
|
reasons:
|
|
|
|
|
|
|
|
- It makes it easier to review code in online editors. This is because engine
|
|
|
|
contributors don't always have access to a full-featured IDE while reviewing
|
|
|
|
code.
|
|
|
|
- It makes the code easier to grasp for beginner contributors (who may not be
|
2024-03-16 20:56:52 +01:00
|
|
|
professional C++ programmers). Pandemonium's codebase is known to be easy to learn
|
2022-03-18 17:46:08 +01:00
|
|
|
from, and we'd like to keep it that way.
|
|
|
|
|
|
|
|
To get your pull request merged, it needs to follow the C++ usage guidelines
|
|
|
|
outlined here. Of course, you can use features not allowed here in your own C++
|
|
|
|
modules or GDNative scripts.
|
|
|
|
|
2023-01-12 20:55:57 +01:00
|
|
|
Note:
|
|
|
|
|
2022-03-18 17:46:08 +01:00
|
|
|
|
2024-03-16 20:56:52 +01:00
|
|
|
Prior to Pandemonium 4.0, the C++ standard used throughout the codebase was C++03,
|
2022-03-18 17:46:08 +01:00
|
|
|
with a handful of C++14 extensions. If you are contributing a pull request
|
|
|
|
to the `3.x` branch rather than `master`, your code can't use C++17 features.
|
|
|
|
Instead, your code must be able to be built with a C++14 compiler.
|
|
|
|
|
|
|
|
The guidelines below don't apply to third-party dependencies, although we
|
|
|
|
generally favor small libraries instead of larger solutions. See also
|
2023-01-12 19:29:11 +01:00
|
|
|
`doc_best_practices_for_engine_contributors`.
|
2022-03-18 17:46:08 +01:00
|
|
|
|
2023-01-12 20:55:57 +01:00
|
|
|
See also:
|
|
|
|
|
2022-03-18 17:46:08 +01:00
|
|
|
|
2023-01-12 19:29:11 +01:00
|
|
|
See `doc_code_style_guidelines` for formatting guidelines.
|
2022-03-18 17:46:08 +01:00
|
|
|
|
|
|
|
Disallowed features
|
|
|
|
-------------------
|
|
|
|
|
2023-01-12 19:43:03 +01:00
|
|
|
**Any feature not listed below is allowed.** Using features like `constexpr`
|
|
|
|
variables and `nullptr` is encouraged when possible. Still, try to keep your
|
2022-03-18 17:46:08 +01:00
|
|
|
use of modern C++ features conservative. Their use needs to serve a real
|
|
|
|
purpose, such as improving code readability or performance.
|
|
|
|
|
|
|
|
Standard Template Library
|
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
|
2023-01-12 20:39:50 +01:00
|
|
|
We don't allow using the `STL ( https://en.wikipedia.org/wiki/Standard_Template_Library )`
|
2024-03-16 20:56:52 +01:00
|
|
|
as Pandemonium provides its own data types (among other things).
|
2023-01-12 19:29:11 +01:00
|
|
|
See `doc_faq_why_not_stl` for more information.
|
2022-03-18 17:46:08 +01:00
|
|
|
|
2023-01-12 19:43:03 +01:00
|
|
|
This means that pull requests should **not** use `std::string`,
|
2024-03-16 20:56:52 +01:00
|
|
|
`std::vector` and the like. Instead, use Pandemonium's datatypes as described below:
|
2022-03-18 17:46:08 +01:00
|
|
|
|
2023-01-12 19:43:03 +01:00
|
|
|
- Use `String` instead of `std::string`.
|
|
|
|
- Use `Vector` instead of `std::vector`. In some cases, `LocalVector`
|
2022-03-18 17:46:08 +01:00
|
|
|
can be used as an alternative (ask core developers first).
|
2023-01-12 19:43:03 +01:00
|
|
|
- Use `Array` instead of `std::array`.
|
2022-03-18 17:46:08 +01:00
|
|
|
|
2023-01-12 20:55:57 +01:00
|
|
|
Note:
|
|
|
|
|
2022-03-18 17:46:08 +01:00
|
|
|
|
2024-03-16 20:56:52 +01:00
|
|
|
Pandemonium also has a List datatype (which is a linked list). While List is already used
|
2022-03-18 17:46:08 +01:00
|
|
|
in the codebase, it typically performs worse than other datatypes like Vector
|
|
|
|
and Array. Therefore, List should be avoided in new code unless necessary.
|
|
|
|
|
2023-01-12 19:43:03 +01:00
|
|
|
`auto` keyword
|
2022-03-18 17:46:08 +01:00
|
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
|
2023-01-12 19:43:03 +01:00
|
|
|
Please don't use the `auto` keyword for type inference. While it can avoid
|
2022-03-18 17:46:08 +01:00
|
|
|
repetition, it can also lead to confusing code:
|
|
|
|
|
2023-01-12 22:00:14 +01:00
|
|
|
```
|
2022-03-18 17:46:08 +01:00
|
|
|
// Not so confusing...
|
|
|
|
auto button = memnew(Button);
|
|
|
|
|
|
|
|
// ...but what about this?
|
|
|
|
auto result = EditorNode::get_singleton()->get_complex_result();
|
2023-01-12 22:00:14 +01:00
|
|
|
```
|
2022-03-18 17:46:08 +01:00
|
|
|
|
|
|
|
Keep in mind hover documentation often isn't readily available for pull request
|
|
|
|
reviewers. Most of the time, reviewers will use GitHub's online viewer to review
|
|
|
|
pull requests.
|
|
|
|
|
2023-01-12 19:43:03 +01:00
|
|
|
We chose to forbid `auto` instead of allowing it on a case-by-case basis to
|
2022-03-18 17:46:08 +01:00
|
|
|
avoid having to decide on difficult edge cases. Thank you for your understanding.
|
|
|
|
|
|
|
|
Lambdas
|
|
|
|
^^^^^^^
|
|
|
|
|
|
|
|
Lambdas should be used conservatively when they make code effectively faster or
|
|
|
|
simpler, and do not impede readability. Please ask before using lambdas in a
|
|
|
|
pull request.
|
|
|
|
|
2023-01-12 19:43:03 +01:00
|
|
|
`#pragma once` directive
|
2022-03-18 17:46:08 +01:00
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
|
2023-01-12 19:43:03 +01:00
|
|
|
To follow the existing style, please use standard `#ifdef`-based include
|
|
|
|
guards instead of `#pragma once` in new files.
|
2022-03-18 17:46:08 +01:00
|
|
|
|
2023-01-12 20:55:57 +01:00
|
|
|
See also:
|
|
|
|
|
2022-03-18 17:46:08 +01:00
|
|
|
|
2023-01-12 19:29:11 +01:00
|
|
|
See `doc_code_style_guidelines_header_includes` for guidelines on sorting
|
2022-03-18 17:46:08 +01:00
|
|
|
includes in C++ and Objective-C files.
|