From 48836a35d89968bb1a6c3b9989b30707cddbdba4 Mon Sep 17 00:00:00 2001 From: Saas Date: Fri, 8 May 2026 21:50:57 +0200 Subject: [PATCH 1/5] first pass on code styleguide --- manual/contributing/code-guidelines.md | 142 +++++++++++++++++++++++++ manual/contributing/index.md | 2 + 2 files changed, 144 insertions(+) create mode 100644 manual/contributing/code-guidelines.md diff --git a/manual/contributing/code-guidelines.md b/manual/contributing/code-guidelines.md new file mode 100644 index 00000000..3466ec32 --- /dev/null +++ b/manual/contributing/code-guidelines.md @@ -0,0 +1,142 @@ +# Contribution Guidelines + +First of all, thanks for taking the time to read these guidelines on how to write code that adheres to the Flax code standards. + +> [!Note] +> These guidelines are not absolute. Please use your best judgment; if a suggestion feels counterproductive or ill-suited to the specific context of the code you are writing, feel free to deviate from it. +> + +> [!Note] +> Some parts of the codebase might break from these guidelines, mostly because they have been existing before this was written or because the note above. Feel free to correct those parts or open an issue on GitHub. +> + +## General + +In general, you should make sure that all code that you contribute to Flax Engine is clean, readable and, if needed, sufficiently commented. + +## Opening a PR + +If your PR is just a few lines of code changed or a *really* obvious change, there is no need to describe what your PR does. However, the bigger in scope the PR is, the more you should make an effort to explain "What?" and "Why?" (something) was changed. + +Ask yourself what information potential reviewers or the person who will merge it might need. Include that in the description of your pull request. + +If you are in doubt wether a specific part of information is necessary, you should probably include it. + +### Common PR Review "pitfalls" +- Cache `FlaxEngine.GUI.Style` in a variable ("`style`") when you are using it multiple times. + +## Codestyle + +> [!Note] +> Some of this might overlap with the [Common C# code conventions](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/coding-conventions). +> + +- TODO: When _variableName vs when without _? +- Don't use file scoped namespaces + +### Use of Curly Braces + +- Don't use `{}` for your loops or if statements if the body of the statement is just one line. If you already are inside two `{}`, always use `{}`, no matter the body's line count. + +### Cases + +- Use `camelCase` +- Use `UpperCamelCase` for constants (`const`) if you are defining it in class scope, use `camelCase` if it's defined in the scope of a method. + +### Declaration Order + +- Constants, fields and properties should be declared in this order: + 1. `protected` + 1. `private` + 1. `public` +- Methods should be declared in this order: + 1. Constructors + 1. `protected` + 1. `private` + 1. `public` +- Constants should be declared first, before all other fields or properties. +- `readonly` fields and properties should be declared first in their respective area +- Properties should be declared after fields in their respective area +- `Action`s should be declared last in their respective area +- Leave a single empty line between variable declarations and the first method/ constructor (in C#). +- If the class requires an empty constructor, it should always be placed on top of all other constructors. + +## XML Documentation Comments + +> [!Tip] +> Most IDEs will automatically create the framework for a documentation comment if you type three `/`. +> + +- Use `/// ` for overriden members that you want to inherit the documentation from their base implementation +- Add a summary to all public or protected members, like this: + +# [C#](#tab/code-csharp-field-xml-summary) +```cs +/// +/// Summary of the member. +/// +public float Foo; +``` +*** +
+ +# [C#](#tab/code-csharp-method-xml-summary) +```cs +/// +/// Summary of the method. +/// +/// Short summary of the `foo` parameter. +/// Short summary of what the method returns. +public string Bar(float foo) +{ + // Method implementation... +} +``` +*** +
+ +- When referring to another class, use the `see` keyword. When referring to another method parameter, use the `paramref` keyword. For example: + +# [C#](#tab/code-csharp-method-xml-summary) +```cs +/// +/// Summary of the method. +/// +/// A float. +/// A (has some relationship with ) +public void Foo(float bar, Color baz) +{ + // Method implementation... +} +``` +*** +
+ +## Deprecation of API + +It can happen that as part of your contribution you want to mark a part of the API as **deprecated**. + +For doing that, use the `[Obsolete]` attribute in C# and the `DEPRECATED()` macro in C++, like in these examples: + +# [C#](#tab/code-csharp) +```cs +/// +/// Summary goes here. +/// [Deprecated in v1.9] +/// +[Obsolete("Helpful deprecation message.")] +public void Foo(); +``` +# [C++](#tab/code-cpp) +```cpp +/// +/// Summary goes here. +/// [Deprecated in v1.9] +/// +DEPRECATED("Helpful deprecation message.") void Foo() const; +``` +*** + +For marking part of an asset as deprecated, use the `MARK_CONTENT_DEPRECATED()` macro in C++ or `ContentDeprecated.Mark();` in C#. + +Deprecated API **should remain in the engine for ~2 years after the release** of the version that the API got deprecated in. \ No newline at end of file diff --git a/manual/contributing/index.md b/manual/contributing/index.md index fe4bdaca..aba8573c 100644 --- a/manual/contributing/index.md +++ b/manual/contributing/index.md @@ -28,6 +28,8 @@ The repository available on GitHub is a mirror of our internal Git repository ho If you want to open the Flax Engine in Visual Studio you might need to install the [Flax Engine Tools for Visual Studio](https://marketplace.visualstudio.com/items?itemName=Flax.FlaxVS) extension (Not needed for Version 1.6 and higher). +You can see guidelines on how to write code for Flax Engine [here](code-guidelines.md). + ### Flax Docs The documentation you're reading right now is hosted as an open project on GitHub [here](https://github.com/FlaxEngine/FlaxDocs). You can fork the repository and edit it to contribute to the project or report issues there. From c0d3a287230e9d99af03b348b69602142f169915 Mon Sep 17 00:00:00 2001 From: Saas Date: Fri, 8 May 2026 22:00:27 +0200 Subject: [PATCH 2/5] clarify camel case usage --- manual/contributing/code-guidelines.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/manual/contributing/code-guidelines.md b/manual/contributing/code-guidelines.md index 3466ec32..76fc7057 100644 --- a/manual/contributing/code-guidelines.md +++ b/manual/contributing/code-guidelines.md @@ -31,7 +31,7 @@ If you are in doubt wether a specific part of information is necessary, you shou > Some of this might overlap with the [Common C# code conventions](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/coding-conventions). > -- TODO: When _variableName vs when without _? +- TODO: When `_variableName` vs when without `_`? - Don't use file scoped namespaces ### Use of Curly Braces @@ -40,7 +40,7 @@ If you are in doubt wether a specific part of information is necessary, you shou ### Cases -- Use `camelCase` +- Use camel case. `UpperCamelCase` for public fields and properties, `camelCase` for everything else. Always use `UpperCamelCase` for method names. - Use `UpperCamelCase` for constants (`const`) if you are defining it in class scope, use `camelCase` if it's defined in the scope of a method. ### Declaration Order From 71a4cdd56851a44d4668a7c07ff65a4d7b93f43f Mon Sep 17 00:00:00 2001 From: Saas Date: Fri, 8 May 2026 22:11:39 +0200 Subject: [PATCH 3/5] pascal case --- manual/contributing/code-guidelines.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/manual/contributing/code-guidelines.md b/manual/contributing/code-guidelines.md index 76fc7057..9adcefdd 100644 --- a/manual/contributing/code-guidelines.md +++ b/manual/contributing/code-guidelines.md @@ -40,8 +40,9 @@ If you are in doubt wether a specific part of information is necessary, you shou ### Cases -- Use camel case. `UpperCamelCase` for public fields and properties, `camelCase` for everything else. Always use `UpperCamelCase` for method names. -- Use `UpperCamelCase` for constants (`const`) if you are defining it in class scope, use `camelCase` if it's defined in the scope of a method. +- Use `PascalCase` for public fields and properties as well as method names. +- Use `camelCase` for everything else. +- Use `PascalCase` for constants (`const`) if you are defining it in class scope, use `camelCase` if it's defined in the scope of a method. ### Declaration Order From 6f43e8c609fe610e535d185e6f7228a55352f556 Mon Sep 17 00:00:00 2001 From: Saas Date: Fri, 8 May 2026 22:17:04 +0200 Subject: [PATCH 4/5] moooooooreee --- manual/contributing/code-guidelines.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/manual/contributing/code-guidelines.md b/manual/contributing/code-guidelines.md index 9adcefdd..34aadd00 100644 --- a/manual/contributing/code-guidelines.md +++ b/manual/contributing/code-guidelines.md @@ -33,6 +33,7 @@ If you are in doubt wether a specific part of information is necessary, you shou - TODO: When `_variableName` vs when without `_`? - Don't use file scoped namespaces +- Place a whitespace between a member, an = and a value. Like this: `foo = 1f;`. ### Use of Curly Braces @@ -62,7 +63,13 @@ If you are in doubt wether a specific part of information is necessary, you shou - Leave a single empty line between variable declarations and the first method/ constructor (in C#). - If the class requires an empty constructor, it should always be placed on top of all other constructors. -## XML Documentation Comments +## Comments + +- Use `// TODO: What is to be done?` or `// HACK: What is hacky?` to mark something that needs work/ to be done or a hack. +- Check your comments for any grammar or spelling mistakes +- Place a space in front of comment contents, like this `// Comment content.` + +### XML Documentation Comments > [!Tip] > Most IDEs will automatically create the framework for a documentation comment if you type three `/`. From 65be63bb1e534a3972e69197b61cc95689ec9c7e Mon Sep 17 00:00:00 2001 From: Saas Date: Sun, 10 May 2026 01:23:04 +0200 Subject: [PATCH 5/5] further clarify some points --- manual/contributing/code-guidelines.md | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/manual/contributing/code-guidelines.md b/manual/contributing/code-guidelines.md index 34aadd00..ec5e9367 100644 --- a/manual/contributing/code-guidelines.md +++ b/manual/contributing/code-guidelines.md @@ -33,10 +33,32 @@ If you are in doubt wether a specific part of information is necessary, you shou - TODO: When `_variableName` vs when without `_`? - Don't use file scoped namespaces -- Place a whitespace between a member, an = and a value. Like this: `foo = 1f;`. +- Place a whitespace between a member, a math symbol and a value. Like for this example: `foo = 1f;`. ### Use of Curly Braces +- Don't use curly braces (`{}`) in a loop or a if statement body if the body line count does allow that (not more than one line). However, use them in an `else` or `else if` statement, no matter the line count. + +# [C#](#tab/code-csharp-curly-braces) +```cs +// No need to use curly braces. +if (myBoolean) + Foo(); + +// Use curly braces here, even if they could be left out for the else if statement. +if (myOtherBoolean) +{ + float myFloat = Bar(); + Foo(myFloat); +} +else if (myInt == 0) +{ + Foo(11f); +} +``` +*** +
+ - Don't use `{}` for your loops or if statements if the body of the statement is just one line. If you already are inside two `{}`, always use `{}`, no matter the body's line count. ### Cases