Add a C++ usage guidelines page

[Calinou]

This page describes C++ features that are used and allowed in Godot's codebase. It's based on community consensus over the last months, as Godot recently moved to C++17 in the master branch.

I've probably missed many things, so please leave comments. That said, the C++ style we expect is now (mostly) set in stone, so most disallowed features written here are not negotiable (such as auto). Please keep the discussion on-topic 🙂

I know @hpvb intended to write this page at first, but I decided to do it to help speed up the process.

This closes godotengine/godot#9694.

[Calinou]

I wrote the part about lambdas this way because we have a few instances of lambdas in the current editor code. These could be rewritten into macros, but it's not really convenient.

We also have a handful of auto keywords in use, but that can be changed more easily.

[akien-mga]

I'd say:

Lambdas should be used conservatively when they make code effectively faster or simpler, and do not impede readability.

[kyleguarco]

Can we add a short section on the appropriate usage of switch cases?

I'm bringing it up because of its inconsistent use throughout the code base, specifically on _notification functions. Some use switches, others use really long if / if-else blocks.

Examples:

• Neat switch cases (scene/gui/line_edit.cpp)
• Neat if block (one case; no switch cases) (scene/gui/panel.cpp)
• Inappropriate use of if blocks (scene/gui/base_button.cpp)
• Inappropriate use of switch cases (scene/2d/line_2d.cpp)
• Another good example of switch cases (scene/main/node.cpp)
• Another example of bad if blocks (scene/main/http_request.cpp)

[Calinou]

@FlashDaggerX Thinking about it, I think we should always use switch in _notification functions, even if there are only 1 or 2 cases. This is to make refactoring easier. When you add new cases, you don't want to spend time converting the if block to a switch block.

[Ansraer]

Could someone explain the reasoning behind disallowing for-range-loops to me?
The docs only mention that they are not explicit enough, but I don't really feel like that's the case. As long as we are only iterating over not overly complex data it should be quite obvious what is happening.

Plus I would argue that the readability and ease of use make them beneficial for "beginner contributors (who may not be
professional C++ programmers)". In my experience, it is a LOT easier to understand for(CustomObject obj : list) than a 70+ characters long custom loop statement.

[NathanLovato]

What's the PR's status? What's missing? Is there a way we can review and merge what's available and consider extending it later?

[Calinou]

@NathanLovato I think this is good to merge as-is, but it would be good to get @akien-mga's approval (especially the part about lambdas).

[fire]

I did a read, and the significant points about autos, STL, and lambdas have been commonly agreed upon by the contributor team.

[Calinou]

Should this page be pushed to 3.4 as-is, with a note saying that it only applies to the master branch? This would help people find it more easily.

We could maintain a dedicated page for 3.x, but it might give people a false impression of what's actually allowed in Godot's C++ codebase since 3.x is restricted to C++14.

[YuriSizov]

I think that notable differences and general code compatibility warning should be a part of the page anyway. People still support 3.x actively, so we should mention the caveats in the docs. Then it wouldn't matter in which version we store the page, as it would be applicable to the development in general.